aiobungie

78@attrs.define(auto_exc=True)
79class AiobungieError(RuntimeError):
80    """Base class that all other exceptions inherit from."""

638@typing.final
639class AmmoType(int, Enum):
640    """AN enum for Detyiny 2 ammo types."""
641
642    NONE = 0
643    PRIMARY = 1
644    SPECIAL = 2
645    HEAVY = 3

171@attrs.define(auto_exc=True)
172class BadRequest(HTTPError):
173    """An exception raised when requesting a resource with the provided data is wrong."""
174
175    url: typedefs.StrOrURL | None
176    """The URL/endpoint caused this error."""
177
178    body: typing.Any
179    """The response body."""
180
181    headers: multidict.CIMultiDictProxy[str]
182    """The response headers."""
183
184    http_status: http.HTTPStatus = attrs.field(
185        default=http.HTTPStatus.BAD_REQUEST, init=False
186    )

693@typing.final
694class ClanMemberType(int, Enum):
695    """An enum for bungie clan member types."""
696
697    NONE = 0
698    BEGINNER = 1
699    MEMBER = 2
700    ADMIN = 3
701    ACTING_FOUNDER = 4
702    FOUNDER = 5

469@typing.final
470class Class(int, Enum):
471    """An Enum for Destiny character classes."""
472
473    TITAN = 0
474    HUNTER = 1
475    WARLOCK = 2
476    UNKNOWN = 3

  56class Client(traits.Compact):
  57    """Compact standard client implementation.
  58
  59    This client is the way to be able to start sending requests over the REST API and receiving deserialized response objects.
  60
  61    Refer to `aiobungie.RESTClient` if you prefer to use a more lower-level client.
  62
  63    Example
  64    -------
  65    ```py
  66    import aiobungie
  67    import asyncio
  68
  69    async def main():
  70        client = aiobungie.Client('token')
  71        async with client.rest:
  72            user = await client.fetch_bungie_user(20315338)
  73            print(user)
  74
  75    asyncio.run(main())
  76    ```
  77
  78    Parameters
  79    -----------
  80    token: `str`
  81        Your Bungie's API key or Token from the developer's portal.
  82
  83    Other Parameters
  84    ----------------
  85    client_secret : `str | None`
  86        An optional application client secret,
  87        This is only needed if you're fetching OAuth2 tokens with this client.
  88    client_id : `int | None`
  89        An optional application client id,
  90        This is only needed if you're fetching OAuth2 tokens with this client.
  91    settings: `aiobungie.builders.Settings | None`
  92        The client settings to use, if `None` the default will be used.
  93    max_retries : `int`
  94        The max retries number to retry if the request hit a `5xx` status code.
  95    debug: `"TRACE" | bool | int`
  96        The level of logging to enable.
  97    """
  98
  99    __slots__ = ("_rest", "_framework")
 100
 101    def __init__(
 102        self,
 103        token: str,
 104        /,
 105        *,
 106        client_secret: str | None = None,
 107        client_id: int | None = None,
 108        settings: builders.Settings | None = None,
 109        max_retries: int = 4,
 110        debug: typing.Literal["TRACE"] | bool | int = False,
 111    ) -> None:
 112        self._rest = rest_.RESTClient(
 113            token,
 114            client_secret=client_secret,
 115            client_id=client_id,
 116            settings=settings,
 117            max_retries=max_retries,
 118            debug=debug,
 119        )
 120
 121        self._framework = framework.Framework()
 122
 123    @property
 124    def framework(self) -> api.Framework:
 125        return self._framework
 126
 127    @property
 128    def rest(self) -> api.RESTClient:
 129        return self._rest
 130
 131    @property
 132    def metadata(self) -> collections.MutableMapping[typing.Any, typing.Any]:
 133        return self._rest.metadata
 134
 135    @property
 136    def settings(self) -> builders.Settings:
 137        return self._rest.settings
 138
 139    # * User methods.
 140
 141    async def fetch_current_user_memberships(self, access_token: str, /) -> user.User:
 142        """Fetch and return a user object of the bungie net user associated with account.
 143
 144        .. warning::
 145            This method requires OAuth2 scope and a Bearer access token.
 146
 147        Parameters
 148        ----------
 149        access_token : `str`
 150            A valid Bearer access token for the authorization.
 151
 152        Returns
 153        -------
 154        `aiobungie.crates.user.User`
 155            A user object includes the Destiny memberships and Bungie.net user.
 156        """
 157        resp = await self.rest.fetch_current_user_memberships(access_token)
 158
 159        return self._framework.deserialize_user(resp)
 160
 161    async def fetch_bungie_user(self, id: int, /) -> user.BungieUser:
 162        """Fetch a Bungie user by their BungieNet id.
 163
 164        Parameters
 165        ----------
 166        id: `int`
 167            The user id.
 168
 169        Returns
 170        -------
 171        `aiobungie.crates.user.BungieUser`
 172            A Bungie user.
 173
 174        Raises
 175        ------
 176        `aiobungie.error.NotFound`
 177            The user was not found.
 178        """
 179        payload = await self.rest.fetch_bungie_user(id)
 180        return self._framework.deserialize_bungie_user(payload)
 181
 182    async def search_users(
 183        self, name: str, /
 184    ) -> sain.Iterator[user.SearchableDestinyUser]:
 185        """Search for players and return all players that matches the same name.
 186
 187        Parameters
 188        ----------
 189        name : `str`
 190            The user name.
 191
 192        Returns
 193        -------
 194        `aiobungie.Iterator[aiobungie.crates.SearchableDestinyUser]`
 195            A sequence of the found users with this name.
 196        """
 197        payload = await self.rest.search_users(name)
 198        return sain.Iter(
 199            self._framework.deserialize_searched_user(user)
 200            for user in payload["searchResults"]
 201        )
 202
 203    async def fetch_user_themes(self) -> collections.Sequence[user.UserThemes]:
 204        """Fetch all available user themes.
 205
 206        Returns
 207        -------
 208        `collections.Sequence[aiobungie.crates.user.UserThemes]`
 209            A sequence of user themes.
 210        """
 211        data = await self.rest.fetch_user_themes()
 212
 213        return self._framework.deserialize_user_themes(data)
 214
 215    async def fetch_hard_types(
 216        self,
 217        credential: int,
 218        type: enums.CredentialType | int = enums.CredentialType.STEAMID,
 219        /,
 220    ) -> user.HardLinkedMembership:
 221        """Gets any hard linked membership given a credential.
 222
 223        Only works for credentials that are public just `aiobungie.CredentialType.STEAMID` right now.
 224        Cross Save aware.
 225
 226        Parameters
 227        ----------
 228        credential: `int`
 229            A valid SteamID64
 230        type: `aiobungie.CredentialType`
 231            The credential type. This must not be changed
 232            Since its only credential that works "currently"
 233
 234        Returns
 235        -------
 236        `aiobungie.crates.user.HardLinkedMembership`
 237            Information about the hard linked data.
 238        """
 239
 240        payload = await self.rest.fetch_hardlinked_credentials(credential, type)
 241
 242        return user.HardLinkedMembership(
 243            id=int(payload["membershipId"]),
 244            type=enums.MembershipType(payload["membershipType"]),
 245            cross_save_type=enums.MembershipType(payload["CrossSaveOverriddenType"]),
 246        )
 247
 248    async def fetch_membership_from_id(
 249        self,
 250        id: int,
 251        /,
 252        type: enums.MembershipType | int = enums.MembershipType.NONE,
 253    ) -> user.User:
 254        """Fetch a Bungie user's memberships from their Bungie ID.
 255
 256        This method returns both Bungie user and its Destiny 2 memberships bound to it.
 257
 258        Parameters
 259        ----------
 260        id : `int`
 261            A Bungie.net user's ID. It looks something like this `20315338`
 262        type : `aiobungie.MembershipType`
 263            The user's membership type. This is optional.
 264
 265        Returns
 266        -------
 267        `aiobungie.crates.User`
 268            A Bungie user with their membership types.
 269
 270        Raises
 271        ------
 272        `aiobungie.NotFound`
 273            The requested user was not found.
 274        """
 275        payload = await self.rest.fetch_membership_from_id(id, type)
 276
 277        return self._framework.deserialize_user(payload)
 278
 279    async def fetch_user_credentials(
 280        self, access_token: str, membership_id: int, /
 281    ) -> collections.Sequence[user.UserCredentials]:
 282        """Fetch an array of credential types attached to the requested account.
 283
 284        .. note::
 285            This method require OAuth2 Bearer access token.
 286
 287        Parameters
 288        ----------
 289        access_token : `str`
 290            The bearer access token associated with the bungie account.
 291        membership_id : `int`
 292            The id of the membership to return.
 293
 294        Returns
 295        -------
 296        `collections.Sequence[aiobungie.crates.UserCredentials]`
 297            A sequence of the attached user credentials.
 298
 299        Raises
 300        ------
 301        `aiobungie.Unauthorized`
 302            The access token was wrong or no access token passed.
 303        """
 304        resp = await self.rest.fetch_user_credentials(access_token, membership_id)
 305
 306        return self._framework.deserialize_user_credentials(resp)
 307
 308    async def fetch_sanitized_membership(
 309        self, membership_id: int, /
 310    ) -> user.SanitizedMembership:
 311        """Fetch a list of all display names linked to `membership_id`, Which is profanity filtered.
 312
 313        Parameters
 314        ----------
 315        membership_id: `int`
 316            The membership ID to fetch
 317
 318        Returns
 319        -------
 320        `aiobungie.crates.SanitizedMembership`
 321            A JSON object contains all the available display names.
 322        """
 323        response = await self._rest.fetch_sanitized_membership(membership_id)
 324        return self._framework.deserialize_sanitized_membership(response)
 325
 326    # * Destiny 2.
 327
 328    async def fetch_profile(
 329        self,
 330        member_id: int,
 331        type: enums.MembershipType | int,
 332        components: collections.Sequence[enums.ComponentType],
 333        auth: str | None = None,
 334    ) -> components.Component:
 335        """Fetch a Bungie profile with the required components.
 336
 337        Example
 338        -------
 339        ```py
 340        my_profile_id = 4611686018484639825
 341        my_profile = await client.fetch_profile(
 342            my_profile_id,
 343            MembershipType.STEAM,
 344            components=(ComponentType.CHARACTERS,)
 345        )
 346        characters = my_profile.characters
 347        if characters is not None:
 348            for character in characters.values():
 349                print(character.power_level)
 350        ```
 351
 352        Parameters
 353        ----------
 354        member_id: `int`
 355            The profile membership's id.
 356        type: `aiobungie.MembershipType`
 357            The profile's membership type.
 358        components : `collections.Sequence[aiobungie.ComponentType]`
 359            A sequence of components to collect. If the sequence is empty, then all components will be `None`.
 360
 361        Other Parameters
 362        ----------------
 363        auth : `str | None`
 364            A Bearer access_token to make the request with.
 365            This is optional and limited to components that only requires an Authorization token.
 366
 367        Returns
 368        --------
 369        `aiobungie.crates.Component`
 370            A Destiny 2 player profile with its components.
 371            Only passed components will be available if they exists. Otherwise they will be `None`
 372
 373        Raises
 374        ------
 375        `aiobungie.MembershipTypeError`
 376            The provided membership type was invalid.
 377        """
 378        data = await self.rest.fetch_profile(member_id, type, components, auth)
 379        return self._framework.deserialize_components(data)
 380
 381    async def fetch_linked_profiles(
 382        self,
 383        member_id: int,
 384        member_type: enums.MembershipType | int,
 385        /,
 386        *,
 387        all: bool = False,
 388    ) -> profile.LinkedProfile:
 389        """Returns a summary information about all profiles linked to the requested member.
 390
 391        The passed membership id/type maybe a Bungie.Net membership or a Destiny memberships.
 392
 393        .. note::
 394            It will only return linked accounts whose linkages you are allowed to view.
 395
 396        Parameters
 397        ----------
 398        member_id : `int`
 399            The ID of the membership. This must be a valid Bungie.Net or PSN or Xbox ID.
 400        member_type : `aiobungie.MembershipType`
 401            The type for the membership whose linked Destiny account you want to return.
 402
 403        Other Parameters
 404        ----------------
 405        all : `bool`
 406            If provided and set to `True`, All memberships regardless
 407            of whether they're obscured by overrides will be returned,
 408
 409            If provided and set to `False`, Only available memberships will be returned.
 410            The default for this is `False`.
 411
 412        Returns
 413        -------
 414        `aiobungie.crates.profile.LinkedProfile`
 415            A linked profile object.
 416        """
 417        resp = await self.rest.fetch_linked_profiles(member_id, member_type, all=all)
 418
 419        return self._framework.deserialize_linked_profiles(resp)
 420
 421    async def fetch_membership(
 422        self,
 423        name: str,
 424        code: int,
 425        /,
 426        type: enums.MembershipType | int = enums.MembershipType.ALL,
 427    ) -> collections.Sequence[user.DestinyMembership]:
 428        """Fetch a Destiny 2 player's memberships.
 429
 430        Parameters
 431        -----------
 432        name: `str`
 433            The unique Bungie player name.
 434        code : `int`
 435            The unique Bungie display name code.
 436        type: `aiobungie.internal.enums.MembershipType`
 437            The player's membership type, e,g. XBOX, STEAM, PSN
 438
 439        Returns
 440        --------
 441        `collections.Sequence[aiobungie.crates.DestinyMembership]`
 442            A sequence of the found Destiny 2 player memberships.
 443            An empty sequence will be returned if no one found.
 444
 445        Raises
 446        ------
 447        `aiobungie.MembershipTypeError`
 448            The provided membership type was invalid.
 449        """
 450        resp = await self.rest.fetch_membership(name, code, type)
 451
 452        return self._framework.deserialize_destiny_memberships(resp)
 453
 454    async def fetch_character(
 455        self,
 456        member_id: int,
 457        membership_type: enums.MembershipType | int,
 458        character_id: int,
 459        components: collections.Sequence[enums.ComponentType],
 460        auth: str | None = None,
 461    ) -> components.CharacterComponent:
 462        """Fetch a Destiny 2 character.
 463
 464        Example
 465        -------
 466        ```py
 467        membership_id, titan_id = 0, 0
 468        my_character = await client.fetch_character(
 469            membership_id,
 470            MembershipType.STEAM,
 471            titan_id,
 472            components=(ComponentType.CHARACTER_INVENTORIES,)
 473        )
 474        inventory = my_character.inventory
 475        if inventory is not None:
 476            for item in inventory.values():
 477                print(item)
 478        ```
 479
 480        Parameters
 481        ----------
 482        member_id: `int`
 483            A valid bungie member id.
 484        character_id: `int`
 485            The Destiny character id to retrieve.
 486        membership_type: `aiobungie.internal.enums.MembershipType`
 487            The member's membership type.
 488        components: `collections.Sequence[aiobungie.ComponentType]`
 489            Multiple arguments of character components to collect and return.
 490
 491        Other Parameters
 492        ----------------
 493        auth : `str | None`
 494            A Bearer access_token to make the request with.
 495            This is optional and limited to components that only requires an Authorization token.
 496
 497        Returns
 498        -------
 499        `aiobungie.crates.CharacterComponent`
 500            A Bungie character component.
 501
 502        `aiobungie.MembershipTypeError`
 503            The provided membership type was invalid.
 504        """
 505        resp = await self.rest.fetch_character(
 506            member_id, membership_type, character_id, components, auth
 507        )
 508
 509        return self._framework.deserialize_character_component(resp)
 510
 511    async def fetch_unique_weapon_history(
 512        self,
 513        membership_id: int,
 514        character_id: int,
 515        membership_type: enums.MembershipType | int,
 516    ) -> collections.Sequence[activity.ExtendedWeaponValues]:
 517        """Fetch details about unique weapon usage for a character. Includes all exotics.
 518
 519        Parameters
 520        ----------
 521        membership_id : `int`
 522            The Destiny user membership id.
 523        character_id : `int`
 524            The character id to retrieve.
 525        membership_type : `aiobungie.aiobungie.MembershipType | int`
 526            The Destiny user's membership type.
 527
 528        Returns
 529        -------
 530        `collections.Sequence[aiobungie.crates.ExtendedWeaponValues]`
 531            A sequence of the weapon's extended values.
 532        """
 533        resp = await self._rest.fetch_unique_weapon_history(
 534            membership_id, character_id, membership_type
 535        )
 536
 537        return tuple(
 538            self._framework.deserialize_extended_weapon_values(weapon)
 539            for weapon in resp["weapons"]
 540        )
 541
 542    # * Destiny 2 Activities.
 543
 544    async def fetch_activities(
 545        self,
 546        member_id: int,
 547        character_id: int,
 548        mode: enums.GameMode | int,
 549        *,
 550        membership_type: enums.MembershipType | int = enums.MembershipType.ALL,
 551        page: int = 0,
 552        limit: int = 250,
 553    ) -> sain.Iterator[activity.Activity]:
 554        """Fetch a Destiny 2 activity for the specified character id.
 555
 556        Parameters
 557        ----------
 558        member_id: `int`
 559            The user id that starts with `4611`.
 560        character_id: `int`
 561            The id of the character to retrieve the activities for.
 562        mode: `aiobungie.aiobungie.internal.enums.GameMode | int`
 563            This parameter filters the game mode, Nightfall, Strike, Iron Banner, etc.
 564
 565        Other Parameters
 566        ----------------
 567        membership_type: `aiobungie.internal.enums.MembershipType`
 568            The Member ship type, if nothing was passed than it will return all.
 569        page: int
 570            The page number. Default is `0`
 571        limit: int
 572            Limit the returned result. Default is `250`.
 573
 574        Returns
 575        -------
 576        `Iterator[aiobungie.crates.Activity]`
 577            An iterator of the player's activities.
 578
 579        Raises
 580        ------
 581        `aiobungie.MembershipTypeError`
 582            The provided membership type was invalid.
 583        """
 584        resp = await self.rest.fetch_activities(
 585            member_id,
 586            character_id,
 587            mode,
 588            membership_type=membership_type,
 589            page=page,
 590            limit=limit,
 591        )
 592
 593        return self._framework.deserialize_activities(resp)
 594
 595    async def fetch_post_activity(self, instance_id: int, /) -> activity.PostActivity:
 596        """Fetch a post activity details.
 597
 598        Parameters
 599        ----------
 600        instance_id: `int`
 601            The activity instance id.
 602
 603        Returns
 604        -------
 605        `aiobungie.crates.PostActivity`
 606           A post activity object.
 607        """
 608        resp = await self.rest.fetch_post_activity(instance_id)
 609
 610        return self._framework.deserialize_post_activity(resp)
 611
 612    async def fetch_aggregated_activity_stats(
 613        self,
 614        character_id: int,
 615        membership_id: int,
 616        membership_type: enums.MembershipType | int,
 617    ) -> sain.Iterator[activity.AggregatedActivity]:
 618        """Fetch aggregated activity stats for a character.
 619
 620        Parameters
 621        ----------
 622        character_id: `int`
 623            The id of the character to retrieve the activities for.
 624        membership_id: `int`
 625            The id of the user that started with `4611`.
 626        membership_type: `aiobungie.internal.enums.MembershipType`
 627            The Member ship type.
 628
 629        Returns
 630        -------
 631        `Iterator[aiobungie.crates.AggregatedActivity]`
 632            An iterator of the player's activities.
 633
 634        Raises
 635        ------
 636        `aiobungie.MembershipTypeError`
 637            The provided membership type was invalid.
 638        """
 639        resp = await self.rest.fetch_aggregated_activity_stats(
 640            character_id, membership_id, membership_type
 641        )
 642
 643        return self._framework.deserialize_aggregated_activities(resp)
 644
 645    # * Destiny 2 Clans or GroupsV2.
 646
 647    async def fetch_clan_from_id(
 648        self,
 649        id: int,
 650        /,
 651        access_token: str | None = None,
 652    ) -> clans.Clan:
 653        """Fetch a Bungie Clan by its id.
 654
 655        Parameters
 656        -----------
 657        id: `int`
 658            The clan id.
 659
 660        Returns
 661        --------
 662        `aiobungie.crates.Clan`
 663            An Bungie clan.
 664
 665        Raises
 666        ------
 667        `aiobungie.NotFound`
 668            The clan was not found.
 669        """
 670        resp = await self.rest.fetch_clan_from_id(id, access_token)
 671
 672        return self._framework.deserialize_clan(resp)
 673
 674    async def fetch_clan(
 675        self,
 676        name: str,
 677        /,
 678        access_token: str | None = None,
 679        *,
 680        type: enums.GroupType | int = enums.GroupType.CLAN,
 681    ) -> clans.Clan:
 682        """Fetch a Clan by its name.
 683        This method will return the first clan found with given name.
 684
 685        Parameters
 686        ----------
 687        name: `str`
 688            The clan name
 689
 690        Other Parameters
 691        ----------------
 692        access_token : `str | None`
 693            An optional access token to make the request with.
 694
 695            If the token was bound to a member of the clan,
 696            This field `aiobungie.crates.Clan.current_user_membership` will be available
 697            and will return the membership of the user who made this request.
 698        type : `aiobungie.GroupType`
 699            The group type, Default is aiobungie.GroupType.CLAN.
 700
 701        Returns
 702        -------
 703        `aiobungie.crates.Clan`
 704            A Bungie clan.
 705
 706        Raises
 707        ------
 708        `aiobungie.NotFound`
 709            The clan was not found.
 710        """
 711        resp = await self.rest.fetch_clan(name, access_token, type=type)
 712
 713        return self._framework.deserialize_clan(resp)
 714
 715    async def fetch_clan_conversations(
 716        self, clan_id: int, /
 717    ) -> collections.Sequence[clans.ClanConversation]:
 718        """Fetch the conversations/chat channels of the given clan id.
 719
 720        Parameters
 721        ----------
 722        clan_id : `int`
 723            The clan id.
 724
 725        Returns
 726        `collections.Sequence[aiobungie.crates.ClanConversation]`
 727            A sequence of the clan chat channels.
 728        """
 729        resp = await self.rest.fetch_clan_conversations(clan_id)
 730
 731        return self._framework.deserialize_clan_conversations(resp)
 732
 733    async def fetch_clan_admins(
 734        self, clan_id: int, /
 735    ) -> sain.Iterator[clans.ClanMember]:
 736        """Fetch the clan founder and admins.
 737
 738        Parameters
 739        ----------
 740        clan_id : `int`
 741            The clan id.
 742
 743        Returns
 744        -------
 745        `aiobungie.Iterator[aiobungie.crates.ClanMember]`
 746            An iterator over the found clan admins and founder.
 747
 748        Raises
 749        ------
 750        `aiobungie.NotFound`
 751            The requested clan was not found.
 752        """
 753        resp = await self.rest.fetch_clan_admins(clan_id)
 754
 755        return self._framework.deserialize_clan_members(resp)
 756
 757    async def fetch_groups_for_member(
 758        self,
 759        member_id: int,
 760        member_type: enums.MembershipType | int,
 761        /,
 762        *,
 763        filter: int = 0,
 764        group_type: enums.GroupType = enums.GroupType.CLAN,
 765    ) -> collections.Sequence[clans.GroupMember]:
 766        """Fetch information about the groups that a given member has joined.
 767
 768        Parameters
 769        ----------
 770        member_id : `int`
 771            The member's id
 772        member_type : `aiobungie.MembershipType`
 773            The member's membership type.
 774
 775        Other Parameters
 776        ----------------
 777        filter : `int`
 778            Filter apply to list of joined groups. This Default to `0`
 779        group_type : `aiobungie.GroupType`
 780            The group's type.
 781            This is always set to `aiobungie.GroupType.CLAN` and should not be changed.
 782
 783        Returns
 784        -------
 785        `collections.Sequence[aiobungie.crates.GroupMember]`
 786            A sequence of joined groups for the fetched member.
 787        """
 788        resp = await self.rest.fetch_groups_for_member(
 789            member_id, member_type, filter=filter, group_type=group_type
 790        )
 791
 792        return tuple(
 793            self._framework.deserialize_group_member(group) for group in resp["results"]
 794        )
 795
 796    async def fetch_potential_groups_for_member(
 797        self,
 798        member_id: int,
 799        member_type: enums.MembershipType | int,
 800        /,
 801        *,
 802        filter: int = 0,
 803        group_type: enums.GroupType | int = enums.GroupType.CLAN,
 804    ) -> collections.Sequence[clans.GroupMember]:
 805        """Fetch the potential groups for a clan member.
 806
 807        Parameters
 808        ----------
 809        member_id : `int`
 810            The member's id
 811        member_type : `aiobungie.aiobungie.MembershipType | int`
 812            The member's membership type.
 813
 814        Other Parameters
 815        ----------------
 816        filter : `int`
 817            Filter apply to list of joined groups. This Default to `0`
 818        group_type : `aiobungie.aiobungie.GroupType | int`
 819            The group's type.
 820            This is always set to `aiobungie.GroupType.CLAN` and should not be changed.
 821
 822        Returns
 823        -------
 824        `collections.Sequence[aiobungie.crates.GroupMember]`
 825            A sequence of joined potential groups for the fetched member.
 826        """
 827        resp = await self.rest.fetch_potential_groups_for_member(
 828            member_id, member_type, filter=filter, group_type=group_type
 829        )
 830
 831        return tuple(
 832            self._framework.deserialize_group_member(group) for group in resp["results"]
 833        )
 834
 835    async def fetch_clan_members(
 836        self,
 837        clan_id: int,
 838        /,
 839        *,
 840        name: str | None = None,
 841        type: enums.MembershipType | int = enums.MembershipType.NONE,
 842    ) -> sain.Iterator[clans.ClanMember]:
 843        """Fetch Bungie clan members.
 844
 845        Parameters
 846        ----------
 847        clan_id : `int`
 848            The clans id
 849
 850        Other Parameters
 851        ----------------
 852        name : `str | None`
 853            If provided, Only players matching this name will be returned.
 854        type : `aiobungie.MembershipType`
 855            An optional clan member's membership type.
 856            This parameter is used to filter the returned results
 857            by the provided membership, For an example XBox memberships only,
 858            Otherwise will return all memberships.
 859
 860        Returns
 861        -------
 862        `Iterator[aiobungie.crates.ClanMember]`
 863            An iterator over the bungie clan members.
 864
 865        Raises
 866        ------
 867        `aiobungie.NotFound`
 868            The clan was not found.
 869        """
 870        resp = await self.rest.fetch_clan_members(clan_id, type=type, name=name)
 871
 872        return self._framework.deserialize_clan_members(resp)
 873
 874    async def fetch_clan_banners(self) -> collections.Sequence[clans.ClanBanner]:
 875        """Fetch the clan banners.
 876
 877        Returns
 878        -------
 879        `collections.Sequence[aiobungie.crates.ClanBanner]`
 880            A sequence of the clan banners.
 881        """
 882        resp = await self.rest.fetch_clan_banners()
 883
 884        return self._framework.deserialize_clan_banners(resp)
 885
 886    # This method is required to be here since it deserialize the clan.
 887    async def kick_clan_member(
 888        self,
 889        access_token: str,
 890        /,
 891        group_id: int,
 892        membership_id: int,
 893        membership_type: enums.MembershipType | int,
 894    ) -> clans.Clan:
 895        """Kick a member from the clan.
 896
 897        .. note::
 898            This request requires OAuth2: oauth2: `AdminGroups` scope.
 899
 900        Parameters
 901        ----------
 902        access_token : `str`
 903            The bearer access token associated with the bungie account.
 904        group_id: `int`
 905            The group id.
 906        membership_id : `int`
 907            The member id to kick.
 908        membership_type : `aiobungie.aiobungie.MembershipType | int`
 909            The member's membership type.
 910
 911        Returns
 912        -------
 913        `aiobungie.crates.clan.Clan`
 914            The clan that the member was kicked from.
 915        """
 916        resp = await self.rest.kick_clan_member(
 917            access_token,
 918            group_id=group_id,
 919            membership_id=membership_id,
 920            membership_type=membership_type,
 921        )
 922
 923        return self._framework.deserialize_clan(resp)
 924
 925    async def fetch_clan_weekly_rewards(self, clan_id: int) -> milestones.Milestone:
 926        """Fetch a Bungie clan's weekly reward state.
 927
 928        Parameters
 929        ----------
 930        clan_id : `int`
 931            The clan's id.
 932
 933        Returns
 934        -------
 935        `aiobungie.crates.Milestone`
 936            A runtime status of the clan's milestone data.
 937        """
 938
 939        resp = await self.rest.fetch_clan_weekly_rewards(clan_id)
 940
 941        return self._framework.deserialize_milestone(resp)
 942
 943    async def search_group(
 944        self,
 945        name: str,
 946        group_type: enums.GroupType | int,
 947        *,
 948        creation_date: clans.GroupDate | int = 0,
 949        sort_by: int | None = None,
 950        group_member_count_filter: typing.Literal[0, 1, 2, 3] | None = None,
 951        locale_filter: str | None = None,
 952        tag_text: str | None = None,
 953        items_per_page: int | None = None,
 954        current_page: int | None = None,
 955        request_token: str | None = None,
 956    ) -> collections.Sequence[clans.Group]:
 957        """Search for groups.
 958
 959        .. note::
 960            If the group type is set to `CLAN`, then parameters `group_member_count_filter`,
 961            `locale_filter` and `tag_text` must be `None`, otherwise `ValueError` will be raised.
 962
 963        Parameters
 964        ----------
 965        name : `str`
 966            The group name.
 967        group_type : `aiobungie.GroupType | int`
 968            The group type that's being searched for.
 969
 970        Other Parameters
 971        ----------------
 972        creation_date : `aiobungie.GroupDate | int`
 973            The creation date of the group. Defaults to `0` which is all time.
 974        sort_by : `int | None`
 975            ...
 976        group_member_count_filter : `int | None`
 977            ...
 978        locale_filter : `str | None`
 979            ...
 980        tag_text : `str | None`
 981            ...
 982        items_per_page : `int | None`
 983            ...
 984        current_page : `int | None`
 985            ...
 986        request_token : `str | None`
 987            ...
 988
 989        Returns
 990        --------
 991        `collections.Sequence[aiobungie.crates.Group]`
 992            An array that contains the groups that match the search criteria.
 993
 994        Raises
 995        ------
 996        `ValueError`
 997            If the group type is `aiobungie.GroupType.CLAN` and `group_member_count_filter`,
 998            `locale_filter` and `tag_text` are not `None`.
 999        """
1000        response = await self._rest.search_group(
1001            name,
1002            group_type,
1003            sort_by=sort_by,
1004            creation_date=creation_date,
1005            group_member_count_filter=group_member_count_filter,
1006            locale_filter=locale_filter,
1007            tag_text=tag_text,
1008            items_per_page=items_per_page,
1009            current_page=current_page,
1010            request_token=request_token,
1011        )
1012        return tuple(
1013            self._framework.deserialize_group(result) for result in response["results"]
1014        )
1015
1016    # * Destiny 2 Entities aka Definitions.
1017
1018    async def fetch_inventory_item(self, hash: int, /) -> entity.InventoryEntity:
1019        """Fetch a static inventory item entity given a its hash.
1020
1021        Parameters
1022        ----------
1023        hash: `int`
1024            Inventory item's hash.
1025
1026        Returns
1027        -------
1028        `aiobungie.crates.InventoryEntity`
1029            A bungie inventory item.
1030        """
1031        resp = await self.rest.fetch_inventory_item(hash)
1032
1033        return self._framework.deserialize_inventory_entity(resp)
1034
1035    async def fetch_objective_entity(self, hash: int, /) -> entity.ObjectiveEntity:
1036        """Fetch a Destiny objective entity given a its hash.
1037
1038        Parameters
1039        ----------
1040        hash: `int`
1041            objective's hash.
1042
1043        Returns
1044        -------
1045        `aiobungie.crates.ObjectiveEntity`
1046            An objective entity item.
1047        """
1048        resp = await self.rest.fetch_objective_entity(hash)
1049
1050        return self._framework.deserialize_objective_entity(resp)
1051
1052    @helpers.unstable
1053    async def search_entities(
1054        self, name: str, entity_type: str, *, page: int = 0
1055    ) -> sain.Iterator[entity.SearchableEntity]:
1056        """Search for Destiny2 entities given a name and its type.
1057
1058        Parameters
1059        ----------
1060        name : `str`
1061            The name of the entity, i.e., Thunderlord, One thousand voices.
1062        entity_type : `str`
1063            The type of the entity, AKA Definition,
1064            For an example `DestinyInventoryItemDefinition` for emblems, weapons, and other inventory items.
1065
1066        Other Parameters
1067        ----------------
1068        page : `int`
1069            An optional page to return. Default to 0.
1070
1071        Returns
1072        -------
1073        `Iterator[aiobungie.crates.SearchableEntity]`
1074            An iterator over the found results matching the provided name.
1075        """
1076        # resp = await self.rest.search_entities(name, entity_type, page=page)
1077        # calling this method will raise anyways.
1078        raise
1079
1080    # Fireteams
1081
1082    async def fetch_fireteams(
1083        self,
1084        activity_type: fireteams.FireteamActivity | int,
1085        *,
1086        platform: fireteams.FireteamPlatform | int = fireteams.FireteamPlatform.ANY,
1087        language: fireteams.FireteamLanguage | str = fireteams.FireteamLanguage.ALL,
1088        date_range: int = 0,
1089        page: int = 0,
1090        slots_filter: int = 0,
1091    ) -> collections.Sequence[fireteams.Fireteam]:
1092        """Fetch public Bungie fireteams with open slots.
1093
1094        Parameters
1095        ----------
1096        activity_type : `aiobungie.aiobungie.crates.FireteamActivity | int`
1097            The fireteam activity type.
1098
1099        Other Parameters
1100        ----------------
1101        platform : `aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int`
1102            If this is provided. Then the results will be filtered with the given platform.
1103            Defaults to `aiobungie.crates.FireteamPlatform.ANY` which returns all platforms.
1104        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
1105            A locale language to filter the used language in that fireteam.
1106            Defaults to `aiobungie.crates.FireteamLanguage.ALL`
1107        date_range : `int`
1108            An integer to filter the date range of the returned fireteams. Defaults to `aiobungie.FireteamDate.ALL`.
1109        page : `int`
1110            The page number. By default its `0` which returns all available activities.
1111        slots_filter : `int`
1112            Filter the returned fireteams based on available slots. Default is `0`
1113
1114        Returns
1115        -------
1116        `collections.Sequence[fireteams.Fireteam]`
1117            A sequence of `aiobungie.crates.Fireteam`.
1118        """
1119
1120        resp = await self.rest.fetch_fireteams(
1121            activity_type,
1122            platform=platform,
1123            language=language,
1124            date_range=date_range,
1125            page=page,
1126            slots_filter=slots_filter,
1127        )
1128
1129        return self._framework.deserialize_fireteams(resp)
1130
1131    async def fetch_available_clan_fireteams(
1132        self,
1133        access_token: str,
1134        group_id: int,
1135        activity_type: fireteams.FireteamActivity | int,
1136        *,
1137        platform: fireteams.FireteamPlatform | int,
1138        language: fireteams.FireteamLanguage | str,
1139        date_range: int = 0,
1140        page: int = 0,
1141        public_only: bool = False,
1142        slots_filter: int = 0,
1143    ) -> collections.Sequence[fireteams.Fireteam]:
1144        """Fetch a clan's fireteams with open slots.
1145
1146        .. note::
1147            This method requires OAuth2: ReadGroups scope.
1148
1149        Parameters
1150        ----------
1151        access_token : `str`
1152            The bearer access token associated with the bungie account.
1153        group_id : `int`
1154            The group/clan id of the fireteam.
1155        activity_type : `aiobungie.aiobungie.crates.FireteamActivity | int`
1156            The fireteam activity type.
1157
1158        Other Parameters
1159        ----------------
1160        platform : `aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int`
1161            If this is provided. Then the results will be filtered with the given platform.
1162            Defaults to `aiobungie.crates.FireteamPlatform.ANY` which returns all platforms.
1163        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
1164            A locale language to filter the used language in that fireteam.
1165            Defaults to `aiobungie.crates.FireteamLanguage.ALL`
1166        date_range : `int`
1167            An integer to filter the date range of the returned fireteams. Defaults to `0`.
1168        page : `int`
1169            The page number. By default its `0` which returns all available activities.
1170        public_only: `bool`
1171            If set to True, Then only public fireteams will be returned.
1172        slots_filter : `int`
1173            Filter the returned fireteams based on available slots. Default is `0`
1174
1175        Returns
1176        -------
1177        `collections.Sequence[aiobungie.crates.Fireteam]`
1178            A sequence of  fireteams found in the clan.
1179            `None` will be returned if nothing was found.
1180        """
1181        resp = await self.rest.fetch_available_clan_fireteams(
1182            access_token,
1183            group_id,
1184            activity_type,
1185            platform=platform,
1186            language=language,
1187            date_range=date_range,
1188            page=page,
1189            public_only=public_only,
1190            slots_filter=slots_filter,
1191        )
1192
1193        return self._framework.deserialize_fireteams(resp)
1194
1195    async def fetch_clan_fireteam(
1196        self, access_token: str, fireteam_id: int, group_id: int
1197    ) -> fireteams.AvailableFireteam:
1198        """Fetch a specific clan fireteam.
1199
1200        .. note::
1201            This method requires OAuth2: ReadGroups scope.
1202
1203        Parameters
1204        ----------
1205        access_token : `str`
1206            The bearer access token associated with the bungie account.
1207        group_id : `int`
1208            The group/clan id to fetch the fireteam from.
1209        fireteam_id : `int`
1210            The fireteam id to fetch.
1211
1212        Returns
1213        -------
1214        `aiobungie.crates.AvailableFireteam`
1215            A sequence of available fireteams objects.
1216        """
1217        resp = await self.rest.fetch_clan_fireteam(access_token, fireteam_id, group_id)
1218
1219        return self._framework.deserialize_available_fireteam(resp)
1220
1221    async def fetch_my_clan_fireteams(
1222        self,
1223        access_token: str,
1224        group_id: int,
1225        *,
1226        include_closed: bool = True,
1227        platform: fireteams.FireteamPlatform | int,
1228        language: fireteams.FireteamLanguage | str,
1229        filtered: bool = True,
1230        page: int = 0,
1231    ) -> collections.Sequence[fireteams.AvailableFireteam]:
1232        """A method that's similar to `fetch_fireteams` but requires OAuth2.
1233
1234        .. note::
1235            This method requires OAuth2: ReadGroups scope.
1236
1237        Parameters
1238        ----------
1239        access_token : str
1240            The bearer access token associated with the bungie account.
1241        group_id : int
1242            The group/clan id to fetch.
1243
1244        Other Parameters
1245        ----------------
1246        include_closed : `bool`
1247            If provided and set to True, It will also return closed fireteams.
1248            If provided and set to False, It will only return public fireteams. Default is True.
1249        platform : aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int
1250            If this is provided. Then the results will be filtered with the given platform.
1251            Defaults to aiobungie.crates.FireteamPlatform.ANY which returns all platforms.
1252        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
1253            A locale language to filter the used language in that fireteam.
1254            Defaults to aiobungie.crates.FireteamLanguage.ALL
1255        filtered : `bool`
1256            If set to True, it will filter by clan. Otherwise not. Default is True.
1257        page : `int`
1258            The page number. By default its 0 which returns all available activities.
1259
1260        Returns
1261        -------
1262        `collections.Sequence[aiobungie.crates.AvailableFireteam]`
1263            A sequence of available fireteams objects if exists. else `None` will be returned.
1264        """
1265        resp = await self.rest.fetch_my_clan_fireteams(
1266            access_token,
1267            group_id,
1268            include_closed=include_closed,
1269            platform=platform,
1270            language=language,
1271            filtered=filtered,
1272            page=page,
1273        )
1274
1275        return self._framework.deserialize_available_fireteams(resp)
1276
1277    # Friends and social.
1278
1279    async def fetch_friends(
1280        self, access_token: str, /
1281    ) -> collections.Sequence[friends.Friend]:
1282        """Fetch bungie friend list.
1283
1284        .. note::
1285            This requests OAuth2: ReadUserData scope.
1286
1287        Parameters
1288        -----------
1289        access_token : `str`
1290            The bearer access token associated with the bungie account.
1291
1292        Returns
1293        -------
1294        `collections.Sequence[aiobungie.crates.Friend]`
1295            A sequence of the friends associated with that access token.
1296        """
1297
1298        resp = await self.rest.fetch_friends(access_token)
1299
1300        return self._framework.deserialize_friends(resp)
1301
1302    async def fetch_friend_requests(
1303        self, access_token: str, /
1304    ) -> friends.FriendRequestView:
1305        """Fetch pending bungie friend requests queue.
1306
1307        .. note::
1308            This requests OAuth2: ReadUserData scope.
1309
1310        Parameters
1311        -----------
1312        access_token : `str`
1313            The bearer access token associated with the bungie account.
1314
1315        Returns
1316        -------
1317        `aiobungie.crates.FriendRequestView`
1318            A friend requests view of that associated access token.
1319        """
1320
1321        resp = await self.rest.fetch_friend_requests(access_token)
1322
1323        return self._framework.deserialize_friend_requests(resp)
1324
1325    # Applications and Developer portal.
1326
1327    async def fetch_application(self, appid: int, /) -> application.Application:
1328        """Fetch a Bungie application.
1329
1330        Parameters
1331        -----------
1332        appid: `int`
1333            The application id.
1334
1335        Returns
1336        --------
1337        `aiobungie.crates.Application`
1338            A Bungie application.
1339        """
1340        resp = await self.rest.fetch_application(appid)
1341
1342        return self._framework.deserialize_application(resp)
1343
1344    # Milestones
1345
1346    async def fetch_public_milestone_content(
1347        self, milestone_hash: int, /
1348    ) -> milestones.MilestoneContent:
1349        """Fetch the milestone content given its hash.
1350
1351        Parameters
1352        ----------
1353        milestone_hash : `int`
1354            The milestone hash.
1355
1356        Returns
1357        -------
1358        `aiobungie.crates.milestones.MilestoneContent`
1359            A milestone content object.
1360        """
1361        ...
1362        resp = await self.rest.fetch_public_milestone_content(milestone_hash)
1363        return self._framework.deserialize_public_milestone_content(resp)