aiobungie.rest

   1# MIT License
   2#
   3# Copyright (c) 2020 = Present nxtlo
   4#
   5# Permission is hereby granted, free of charge, to typing.Any person obtaining a copy
   6# of this software and associated documentation files (the "Software"), to deal
   7# in the Software without restriction, including without limitation the rights
   8# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9# copies of the Software, and to permit persons to whom the Software is
  10# furnished to do so, subject to the following conditions:
  11#
  12# The above copyright notice and this permission notice shall be included in all
  13# copies or substantial portions of the Software.
  14#
  15# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF typing.Any KIND, EXPRESS OR
  16# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR typing.Any CLAIM, DAMAGES OR OTHER
  19# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  21# SOFTWARE.
  22
  23"""Basic implementation of a RESTful clients for Bungie's REST API."""
  24
  25from __future__ import annotations
  26
  27__all__ = ("RESTClient", "RESTPool", "TRACE")
  28
  29import asyncio
  30import contextlib
  31import datetime
  32import http
  33import logging
  34import logging.config
  35import os
  36import pathlib
  37import sys
  38import typing
  39import uuid
  40import zipfile
  41
  42import aiohttp
  43
  44from aiobungie import api, builders, error, metadata, typedefs, url
  45from aiobungie.crates import clans, fireteams
  46from aiobungie.internal import _backoff as backoff
  47from aiobungie.internal import enums, helpers, time
  48
  49if typing.TYPE_CHECKING:
  50    import collections.abc as collections
  51    import concurrent.futures
  52    import types
  53
  54    _HTTP_METHOD = typing.Literal["GET", "DELETE", "POST", "PUT", "PATCH"]
  55    _ALLOWED_LANGS = typing.Literal[
  56        "en",
  57        "fr",
  58        "es",
  59        "es-mx",
  60        "de",
  61        "it",
  62        "ja",
  63        "pt-br",
  64        "ru",
  65        "pl",
  66        "ko",
  67        "zh-cht",
  68        "zh-chs",
  69    ]
  70
  71_MANIFEST_LANGUAGES: typing.Final[frozenset[_ALLOWED_LANGS]] = frozenset(
  72    (
  73        "en",
  74        "fr",
  75        "es",
  76        "es-mx",
  77        "de",
  78        "it",
  79        "ja",
  80        "pt-br",
  81        "ru",
  82        "pl",
  83        "ko",
  84        "zh-cht",
  85        "zh-chs",
  86    )
  87)
  88
  89# Client headers.
  90_APP_JSON: str = "application/json"
  91_AUTH_HEADER: str = sys.intern("Authorization")
  92_USER_AGENT_HEADERS: str = sys.intern("User-Agent")
  93_USER_AGENT: str = (
  94    f"AiobungieClient (Author: {metadata.__author__}), "
  95    f"(Version: {metadata.__version__}), (URL: {metadata.__url__})"
  96)
  97
  98# Possible internal error codes.
  99_RETRY_5XX: set[int] = {500, 502, 503, 504}
 100
 101# HTTP methods.
 102_GET: typing.Final[str] = "GET"
 103_POST: typing.Final[str] = "POST"
 104
 105# These are Currently unused.
 106# _DELETE: typing.Final[str] = "DELETE"
 107# _PUT: typing.Final[str] = "PUT"
 108# _PATCH: typing.Final[str] = "PATCH"
 109
 110
 111_LOGGER = logging.getLogger("aiobungie.rest")
 112
 113TRACE: typing.Final[int] = logging.DEBUG - 5
 114"""The trace logging level for the `RESTClient` responses.
 115
 116You can enable this with the following code
 117
 118>>> import logging
 119>>> logging.getLogger("aiobungie.rest").setLevel(aiobungie.TRACE)
 120# or
 121>>> logging.basicConfig(level=aiobungie.TRACE)
 122# Or
 123>>> client = aiobungie.RESTClient(debug="TRACE")
 124# Or if you're using `aiobungie.Client`
 125>>> client = aiobungie.Client()
 126>>> client.rest.with_debug(level=aiobungie.TRACE, file="rest_logs.txt")
 127"""
 128
 129logging.addLevelName(TRACE, "TRACE")
 130
 131
 132def _collect_components(
 133    components: collections.Sequence[enums.ComponentType],
 134    /,
 135) -> str:
 136    collector: collections.MutableSequence[str] = []
 137
 138    for component in components:
 139        if isinstance(component.value, tuple):
 140            collector.extend(str(c) for c in component.value)  # pyright: ignore
 141        else:
 142            collector.append(str(component.value))
 143    return ",".join(collector)
 144
 145
 146def _uuid() -> str:
 147    return uuid.uuid4().hex
 148
 149
 150def _ensure_manifest_language(language: str) -> None:
 151    if language not in _MANIFEST_LANGUAGES:
 152        langs = "\n".join(_MANIFEST_LANGUAGES)
 153        raise ValueError(
 154            f"{language} is not a valid manifest language, "
 155            f"valid languages are: {langs}"
 156        )
 157
 158
 159def _get_path(
 160    file_name: str, path: str | pathlib.Path, sql: bool = False
 161) -> pathlib.Path:
 162    if sql:
 163        return pathlib.Path(path).joinpath(file_name + ".sqlite3")
 164    return pathlib.Path(path).joinpath(file_name + ".json")
 165
 166
 167def _write_json_bytes(
 168    data: bytes,
 169    file_name: str = "manifest",
 170    path: pathlib.Path | str = "./",
 171) -> None:
 172    with _get_path(file_name, path).open("wb") as p:
 173        p.write(helpers.dumps(helpers.loads(data)))
 174
 175
 176def _write_sqlite_bytes(
 177    data: bytes,
 178    path: pathlib.Path | str = "./",
 179    file_name: str = "manifest",
 180) -> None:
 181    with open(f"{_uuid()}.zip", "wb") as tmp:
 182        tmp.write(data)
 183        try:
 184            with zipfile.ZipFile(tmp.name) as zipped:
 185                file = zipped.namelist()
 186
 187                if file:
 188                    zipped.extractall(".")
 189
 190                    os.rename(file[0], _get_path(file_name, path, sql=True))
 191
 192        finally:
 193            pathlib.Path(tmp.name).unlink(missing_ok=True)
 194
 195
 196class _JSONPayload(aiohttp.BytesPayload):
 197    def __init__(
 198        self, value: typing.Any, dumps: typedefs.Dumps = helpers.dumps
 199    ) -> None:
 200        super().__init__(dumps(value), content_type=_APP_JSON, encoding="utf-8")
 201
 202
 203class RESTPool:
 204    """a Pool of `RESTClient` instances that shares the same TCP client connection.
 205
 206    This allows you to acquire instances of `RESTClient`s from single settings and credentials.
 207
 208    Example
 209    -------
 210    ```py
 211    import aiobungie
 212    import asyncio
 213
 214    pool = aiobungie.RESTPool("token")
 215
 216    async def get() -> None:
 217        await pool.start()
 218
 219        async with pool.acquire() as client:
 220            await client.fetch_character(...)
 221
 222        await pool.stop()
 223
 224    asyncio.run(get())
 225    ```
 226
 227    Parameters
 228    ----------
 229    token : `str`
 230        A valid application token from Bungie's developer portal.
 231
 232    Other Parameters
 233    ----------------
 234    client_secret : `str | None`
 235        An optional application client secret,
 236        This is only needed if you're fetching OAuth2 tokens with this client.
 237    client_id : `int | None`
 238        An optional application client id,
 239        This is only needed if you're fetching OAuth2 tokens with this client.
 240    settings: `aiobungie.builders.Settings | None`
 241        The client settings to use, if `None` the default will be used.
 242    max_retries : `int`
 243        The max retries number to retry if the request hit a `5xx` status code.
 244    debug : `bool | str`
 245        Whether to enable logging responses or not.
 246
 247    Logging Levels
 248    --------------
 249    * `False`: This will disable logging.
 250    * `True`: This will set the level to `DEBUG` and enable logging minimal information.
 251    Like the response status, route, taken time and so on.
 252    * `"TRACE" | aiobungie.TRACE`: This will log the response headers along with the minimal information.
 253    """
 254
 255    __slots__ = (
 256        "_token",
 257        "_max_retries",
 258        "_client_secret",
 259        "_client_id",
 260        "_metadata",
 261        "_enable_debug",
 262        "_client_session",
 263        "_loads",
 264        "_dumps",
 265        "_settings",
 266    )
 267
 268    # Looks like mypy doesn't like this.
 269    if typing.TYPE_CHECKING:
 270        _enable_debug: typing.Literal["TRACE"] | bool | int
 271
 272    def __init__(
 273        self,
 274        token: str,
 275        /,
 276        *,
 277        client_secret: str | None = None,
 278        client_id: int | None = None,
 279        settings: builders.Settings | None = None,
 280        dumps: typedefs.Dumps = helpers.dumps,
 281        loads: typedefs.Loads = helpers.loads,
 282        max_retries: int = 4,
 283        debug: typing.Literal["TRACE"] | bool | int = False,
 284    ) -> None:
 285        self._client_secret = client_secret
 286        self._client_id = client_id
 287        self._token = token
 288        self._max_retries = max_retries
 289        self._metadata: collections.MutableMapping[typing.Any, typing.Any] = {}
 290        self._enable_debug = debug
 291        self._client_session: aiohttp.ClientSession | None = None
 292        self._loads = loads
 293        self._dumps = dumps
 294        self._settings = settings or builders.Settings()
 295
 296    @property
 297    def client_id(self) -> int | None:
 298        """Return the client id of this REST client if provided, Otherwise None."""
 299        return self._client_id
 300
 301    @property
 302    def metadata(self) -> collections.MutableMapping[typing.Any, typing.Any]:
 303        """A general-purpose mutable mapping you can use to store data.
 304
 305        This mapping can be accessed from any process that has a reference to this pool.
 306        """
 307        return self._metadata
 308
 309    @property
 310    def settings(self) -> builders.Settings:
 311        """Internal client settings used within the HTTP client session."""
 312        return self._settings
 313
 314    @typing.overload
 315    def build_oauth2_url(self, client_id: int) -> builders.OAuthURL: ...
 316
 317    @typing.overload
 318    def build_oauth2_url(self) -> builders.OAuthURL | None: ...
 319
 320    @typing.final
 321    def build_oauth2_url(
 322        self, client_id: int | None = None
 323    ) -> builders.OAuthURL | None:
 324        """Construct a new `OAuthURL` url object.
 325
 326        You can get the complete string representation of the url by calling `.compile()` on it.
 327
 328        Parameters
 329        ----------
 330        client_id : `int | None`
 331            An optional client id to provide, If left `None` it will roll back to the id passed
 332            to the `RESTClient`, If both is `None` this method will return `None`.
 333
 334        Returns
 335        -------
 336        `aiobungie.builders.OAuthURL | None`
 337            * If `client_id` was provided as a parameter, It guarantees to return a complete `OAuthURL` object
 338            * If `client_id` is set to `aiobungie.RESTClient` will be.
 339            * If both are `None` this method will return `None.
 340        """
 341        client_id = client_id or self._client_id
 342        if client_id is None:
 343            return None
 344
 345        return builders.OAuthURL(client_id=client_id)
 346
 347    async def start(self) -> None:
 348        """Start the TCP connection of this client pool.
 349
 350        This will raise `RuntimeError` if the connection has already been started.
 351
 352        Example
 353        -------
 354        ```py
 355        pool = aiobungie.RESTPool(...)
 356
 357        async def run() -> None:
 358            await pool.start()
 359            async with pool.acquire() as client:
 360                # use client
 361
 362        async def stop(self) -> None:
 363            await pool.close()
 364        ```
 365        """
 366        if self._client_session is not None:
 367            raise RuntimeError("<RESTPool> has already been started.") from None
 368
 369        self._client_session = aiohttp.ClientSession(
 370            connector=aiohttp.TCPConnector(
 371                use_dns_cache=self._settings.use_dns_cache,
 372                ttl_dns_cache=self._settings.ttl_dns_cache,
 373                ssl_context=self._settings.ssl_context,
 374                ssl=self._settings.ssl,
 375            ),
 376            connector_owner=True,
 377            raise_for_status=False,
 378            timeout=self._settings.http_timeout,
 379            trust_env=self._settings.trust_env,
 380            headers=self._settings.headers,
 381        )
 382
 383    async def stop(self) -> None:
 384        """Stop the TCP connection of this client pool.
 385
 386        This will raise `RuntimeError` if the connection has already been closed.
 387
 388        Example
 389        -------
 390        ```py
 391        pool = aiobungie.RESTPool(...)
 392
 393        async def run() -> None:
 394            await pool.start()
 395            async with pool.acquire() as client:
 396                # use client
 397
 398        async def stop(self) -> None:
 399            await pool.close()
 400        ```
 401        """
 402        if self._client_session is None:
 403            raise RuntimeError("<RESTPool> is already stopped.")
 404
 405        await self._client_session.close()
 406        self._client_session = None
 407
 408    @typing.final
 409    def acquire(self) -> RESTClient:
 410        """Acquires a new `RESTClient` instance from this pool.
 411
 412        Returns
 413        -------
 414        `RESTClient`
 415            An instance of a `RESTClient`.
 416        """
 417        return RESTClient(
 418            self._token,
 419            client_secret=self._client_secret,
 420            client_id=self._client_id,
 421            loads=self._loads,
 422            dumps=self._dumps,
 423            max_retries=self._max_retries,
 424            debug=self._enable_debug,
 425            client_session=self._client_session,
 426            owned_client=False,
 427            settings=self._settings,
 428        )
 429
 430
 431class RESTClient(api.RESTClient):
 432    """A single process REST client implementation.
 433
 434    This client is designed to only make HTTP requests and return raw JSON objects.
 435
 436    Example
 437    -------
 438    ```py
 439    import aiobungie
 440
 441    client = aiobungie.RESTClient("TOKEN")
 442    async with client:
 443        response = await client.fetch_clan_members(4389205)
 444        for member in response['results']:
 445            print(member['destinyUserInfo'])
 446    ```
 447
 448    Parameters
 449    ----------
 450    token : `str`
 451        A valid application token from Bungie's developer portal.
 452
 453    Other Parameters
 454    ----------------
 455    client_secret : `str | None`
 456        An optional application client secret,
 457        This is only needed if you're fetching OAuth2 tokens with this client.
 458    client_id : `int | None`
 459        An optional application client id,
 460        This is only needed if you're fetching OAuth2 tokens with this client.
 461    settings: `aiobungie.builders.Settings | None`
 462        The client settings to use, if `None` the default will be used.
 463    owned_client: `bool`
 464        * If set to `True`, this client will use the provided `client_session` parameter instead,
 465        * If set to `True` and `client_session` is `None`, `ValueError` will be raised.
 466        * If set to `False`, aiobungie will initialize a new client session for you.
 467
 468    client_session: `aiohttp.ClientSession | None`
 469        If provided, this client session will be used to make all the HTTP requests.
 470        The `owned_client` must be set to `True` for this to work.
 471    max_retries : `int`
 472        The max retries number to retry if the request hit a `5xx` status code.
 473    debug : `bool | str`
 474        Whether to enable logging responses or not.
 475
 476    Logging Levels
 477    --------------
 478    * `False`: This will disable logging.
 479    * `True`: This will set the level to `DEBUG` and enable logging minimal information.
 480    * `"TRACE" | aiobungie.TRACE`: This will log the response headers along with the minimal information.
 481    """
 482
 483    __slots__ = (
 484        "_token",
 485        "_session",
 486        "_lock",
 487        "_max_retries",
 488        "_client_secret",
 489        "_client_id",
 490        "_metadata",
 491        "_dumps",
 492        "_loads",
 493        "_owned_client",
 494        "_settings",
 495    )
 496
 497    def __init__(
 498        self,
 499        token: str,
 500        /,
 501        *,
 502        client_secret: str | None = None,
 503        client_id: int | None = None,
 504        settings: builders.Settings | None = None,
 505        owned_client: bool = True,
 506        client_session: aiohttp.ClientSession | None = None,
 507        dumps: typedefs.Dumps = helpers.dumps,
 508        loads: typedefs.Loads = helpers.loads,
 509        max_retries: int = 4,
 510        debug: typing.Literal["TRACE"] | bool | int = False,
 511    ) -> None:
 512        if owned_client is False and client_session is None:
 513            raise ValueError(
 514                "Expected an owned client session, but got `None`, Cannot have `owned_client` set to `False` and `client_session` to `None`"
 515            )
 516
 517        self._settings = settings or builders.Settings()
 518        self._session = client_session
 519        self._owned_client = owned_client
 520        self._lock: asyncio.Lock | None = None
 521        self._client_secret = client_secret
 522        self._client_id = client_id
 523        self._token: str = token
 524        self._max_retries = max_retries
 525        self._dumps = dumps
 526        self._loads = loads
 527        self._metadata: collections.MutableMapping[typing.Any, typing.Any] = {}
 528        self.with_debug(debug)
 529
 530    @property
 531    def client_id(self) -> int | None:
 532        return self._client_id
 533
 534    @property
 535    def metadata(self) -> collections.MutableMapping[typing.Any, typing.Any]:
 536        return self._metadata
 537
 538    @property
 539    def is_alive(self) -> bool:
 540        return self._session is not None
 541
 542    @property
 543    def settings(self) -> builders.Settings:
 544        return self._settings
 545
 546    async def close(self) -> None:
 547        if self._session is None:
 548            raise RuntimeError("REST client is not running.")
 549
 550        if self._owned_client:
 551            await self._session.close()
 552            self._session = None
 553
 554    def open(self) -> None:
 555        """Open a new client session. This is called internally with contextmanager usage."""
 556        if self.is_alive and self._owned_client:
 557            raise RuntimeError("Cannot open REST client when it's already open.")
 558
 559        if self._owned_client:
 560            self._session = aiohttp.ClientSession(
 561                connector=aiohttp.TCPConnector(
 562                    use_dns_cache=self._settings.use_dns_cache,
 563                    ttl_dns_cache=self._settings.ttl_dns_cache,
 564                    ssl_context=self._settings.ssl_context,
 565                    ssl=self._settings.ssl,
 566                ),
 567                connector_owner=True,
 568                raise_for_status=False,
 569                timeout=self._settings.http_timeout,
 570                trust_env=self._settings.trust_env,
 571                headers=self._settings.headers,
 572            )
 573
 574    @typing.final
 575    async def static_request(
 576        self,
 577        method: _HTTP_METHOD,
 578        path: str,
 579        *,
 580        auth: str | None = None,
 581        json: collections.Mapping[str, typing.Any] | None = None,
 582        params: collections.Mapping[str, typing.Any] | None = None,
 583    ) -> typedefs.JSONIsh:
 584        return await self._request(method, path, auth=auth, json=json, params=params)
 585
 586    @typing.overload
 587    def build_oauth2_url(self, client_id: int) -> builders.OAuthURL: ...
 588
 589    @typing.overload
 590    def build_oauth2_url(self) -> builders.OAuthURL | None: ...
 591
 592    @typing.final
 593    def build_oauth2_url(
 594        self, client_id: int | None = None
 595    ) -> builders.OAuthURL | None:
 596        client_id = client_id or self._client_id
 597        if client_id is None:
 598            return None
 599
 600        return builders.OAuthURL(client_id=client_id)
 601
 602    @typing.final
 603    async def _request(
 604        self,
 605        method: _HTTP_METHOD,
 606        route: str,
 607        *,
 608        base: bool = False,
 609        oauth2: bool = False,
 610        auth: str | None = None,
 611        unwrap_bytes: bool = False,
 612        json: collections.Mapping[str, typing.Any] | None = None,
 613        data: collections.Mapping[str, typing.Any] | None = None,
 614        params: collections.Mapping[str, typing.Any] | None = None,
 615    ) -> typedefs.JSONIsh:
 616        # This is not None when opening the client.
 617        assert self._session is not None, (
 618            "This client hasn't been opened yet. Use `async with client` or `async with client.rest` "
 619            "before performing any request."
 620        )
 621
 622        retries: int = 0
 623        headers: collections.MutableMapping[str, typing.Any] = {}
 624
 625        headers[_USER_AGENT_HEADERS] = _USER_AGENT
 626        headers["X-API-KEY"] = self._token
 627
 628        if auth is not None:
 629            headers[_AUTH_HEADER] = f"Bearer {auth}"
 630
 631        # Handling endpoints
 632        endpoint = url.BASE
 633
 634        if not base:
 635            endpoint = endpoint + url.REST_EP
 636
 637        if oauth2:
 638            assert self._client_id, "Client ID is required to make authorized requests."
 639            assert (
 640                self._client_secret
 641            ), "Client secret is required to make authorized requests."
 642            headers["client_secret"] = self._client_secret
 643
 644            headers["Content-Type"] = "application/x-www-form-urlencoded"
 645            endpoint = endpoint + url.TOKEN_EP
 646
 647        if self._lock is None:
 648            self._lock = asyncio.Lock()
 649
 650        if json:
 651            headers["Content-Type"] = _APP_JSON
 652
 653        stack = contextlib.AsyncExitStack()
 654        while True:
 655            try:
 656                await stack.enter_async_context(self._lock)
 657
 658                # We make the request here.
 659                taken_time = time.monotonic()
 660                response = await self._session.request(
 661                    method=method,
 662                    url=f"{endpoint}/{route}",
 663                    headers=headers,
 664                    data=_JSONPayload(json) if json else data,
 665                    params=params,
 666                )
 667                response_time = (time.monotonic() - taken_time) * 1_000
 668
 669                _LOGGER.debug(
 670                    "METHOD: %s ROUTE: %s STATUS: %i ELAPSED: %.4fms",
 671                    method,
 672                    f"{endpoint}/{route}",
 673                    response.status,
 674                    response_time,
 675                )
 676
 677                await self._handle_ratelimit(response, method, route)
 678
 679            except aiohttp.ClientConnectionError as exc:
 680                if retries >= self._max_retries:
 681                    raise error.HTTPError(
 682                        str(exc),
 683                        http.HTTPStatus.SERVICE_UNAVAILABLE,
 684                    )
 685                backoff_ = backoff.ExponentialBackOff(maximum=8)
 686
 687                timer = next(backoff_)
 688                _LOGGER.warning(
 689                    "Client received a connection error <%s> Retrying in %.2fs. Remaining retries: %s",
 690                    type(exc).__qualname__,
 691                    timer,
 692                    self._max_retries - retries,
 693                )
 694                retries += 1
 695                await asyncio.sleep(timer)
 696                continue
 697
 698            finally:
 699                await stack.aclose()
 700
 701            if response.status == http.HTTPStatus.NO_CONTENT:
 702                return None
 703
 704            # Handle the successful response.
 705            if 300 > response.status >= 200:
 706                if unwrap_bytes:
 707                    # We need to read the bytes for the manifest response.
 708                    return await response.read()
 709
 710                # Bungie get funky and return HTML instead of JSON when making an authorized
 711                # request with a dummy access token. We could technically read the page content
 712                # but that's Bungie's fault for not returning a JSON response.
 713                if response.content_type != _APP_JSON:
 714                    raise error.HTTPError(
 715                        message=f"Expected JSON response, Got {response.content_type}, "
 716                        f"{response.real_url.human_repr()}",
 717                        http_status=http.HTTPStatus(response.status),
 718                    )
 719
 720                json_data = self._loads(await response.read())
 721
 722                if _LOGGER.isEnabledFor(TRACE):
 723                    _LOGGER.log(
 724                        TRACE,
 725                        "%s",
 726                        error.stringify_headers(dict(response.headers)),
 727                    )
 728
 729                    details: collections.MutableMapping[str, typing.Any] = {}
 730                    if json:
 731                        details["json"] = error.filtered_headers(json)
 732
 733                    if data:
 734                        details["data"] = error.filtered_headers(data)
 735
 736                    if params:
 737                        details["params"] = error.filtered_headers(params)
 738
 739                    if details:
 740                        _LOGGER.log(TRACE, "%s", error.stringify_headers(details))
 741
 742                # Return the response.
 743                # auth responses are not inside a Response object.
 744                if oauth2:
 745                    return json_data
 746
 747                # The reason we have a type ignore is because the actual response type
 748                # is within this `Response` key.
 749                return json_data["Response"]  # type: ignore
 750
 751            if (
 752                response.status in _RETRY_5XX and retries < self._max_retries  # noqa: W503
 753            ):
 754                backoff_ = backoff.ExponentialBackOff(maximum=6)
 755                sleep_time = next(backoff_)
 756                _LOGGER.warning(
 757                    "Got %i - %s. Sleeping for %.2f seconds. Remaining retries: %i",
 758                    response.status,
 759                    response.reason,
 760                    sleep_time,
 761                    self._max_retries - retries,
 762                )
 763
 764                retries += 1
 765                await asyncio.sleep(sleep_time)
 766                continue
 767
 768            raise await error.panic(response)
 769
 770    async def __aenter__(self) -> RESTClient:
 771        self.open()
 772        return self
 773
 774    async def __aexit__(
 775        self,
 776        exception_type: type[BaseException] | None,
 777        exception: BaseException | None,
 778        exception_traceback: types.TracebackType | None,
 779    ) -> None:
 780        await self.close()
 781
 782    # We don't want this to be super complicated.
 783    async def _handle_ratelimit(
 784        self,
 785        response: aiohttp.ClientResponse,
 786        method: str,
 787        route: str,
 788    ) -> None:
 789        if response.status != http.HTTPStatus.TOO_MANY_REQUESTS:
 790            return
 791
 792        if response.content_type != _APP_JSON:
 793            raise error.HTTPError(
 794                f"Being ratelimited on non JSON request, {response.content_type}.",
 795                http.HTTPStatus.TOO_MANY_REQUESTS,
 796            )
 797
 798        # The reason we have a type ignore here is that we guaranteed the content type is JSON above.
 799        json: typedefs.JSONObject = self._loads(await response.read())  # type: ignore
 800        retry_after = float(json.get("ThrottleSeconds", 15.0)) + 0.1
 801        max_calls: int = 0
 802
 803        while True:
 804            if max_calls == 10:
 805                # Max retries by default. We raise an error here.
 806                raise error.RateLimitedError(
 807                    body=json,
 808                    url=str(response.real_url),
 809                    retry_after=retry_after,
 810                )
 811
 812            # We sleep for a little bit to avoid funky behavior.
 813            _LOGGER.warning(
 814                "We're being ratelimited, Method %s Route %s. Sleeping for %.2fs.",
 815                method,
 816                route,
 817                retry_after,
 818            )
 819            await asyncio.sleep(retry_after)
 820            max_calls += 1
 821            continue
 822
 823    async def fetch_oauth2_tokens(self, code: str, /) -> builders.OAuth2Response:
 824        data = {
 825            "grant_type": "authorization_code",
 826            "code": code,
 827            "client_id": self._client_id,
 828            "client_secret": self._client_secret,
 829        }
 830
 831        response = await self._request(_POST, "", data=data, oauth2=True)
 832        assert isinstance(response, dict)
 833        return builders.OAuth2Response.build_response(response)
 834
 835    async def refresh_access_token(
 836        self, refresh_token: str, /
 837    ) -> builders.OAuth2Response:
 838        data = {
 839            "grant_type": "refresh_token",
 840            "refresh_token": refresh_token,
 841            "client_id": self._client_id,
 842            "client_secret": self._client_secret,
 843        }
 844
 845        response = await self._request(_POST, "", data=data, oauth2=True)
 846        assert isinstance(response, dict)
 847        return builders.OAuth2Response.build_response(response)
 848
 849    async def fetch_bungie_user(self, id: int) -> typedefs.JSONObject:
 850        resp = await self._request(_GET, f"User/GetBungieNetUserById/{id}/")
 851        assert isinstance(resp, dict)
 852        return resp
 853
 854    async def fetch_user_themes(self) -> typedefs.JSONArray:
 855        resp = await self._request(_GET, "User/GetAvailableThemes/")
 856        assert isinstance(resp, list)
 857        return resp
 858
 859    async def fetch_membership_from_id(
 860        self,
 861        id: int,
 862        type: enums.MembershipType | int = enums.MembershipType.NONE,
 863        /,
 864    ) -> typedefs.JSONObject:
 865        resp = await self._request(_GET, f"User/GetMembershipsById/{id}/{int(type)}")
 866        assert isinstance(resp, dict)
 867        return resp
 868
 869    async def fetch_membership(
 870        self,
 871        name: str,
 872        code: int,
 873        type: enums.MembershipType | int = enums.MembershipType.ALL,
 874        /,
 875    ) -> typedefs.JSONArray:
 876        resp = await self._request(
 877            _POST,
 878            f"Destiny2/SearchDestinyPlayerByBungieName/{int(type)}",
 879            json={"displayName": name, "displayNameCode": code},
 880        )
 881        assert isinstance(resp, list)
 882        return resp
 883
 884    async def fetch_sanitized_membership(
 885        self, membership_id: int, /
 886    ) -> typedefs.JSONObject:
 887        response = await self._request(
 888            _GET, f"User/GetSanitizedPlatformDisplayNames/{membership_id}/"
 889        )
 890        assert isinstance(response, dict)
 891        return response
 892
 893    async def search_users(self, name: str, /) -> typedefs.JSONObject:
 894        resp = await self._request(
 895            _POST,
 896            "User/Search/GlobalName/0",
 897            json={"displayNamePrefix": name},
 898        )
 899        assert isinstance(resp, dict)
 900        return resp
 901
 902    async def fetch_clan_from_id(
 903        self, id: int, /, access_token: str | None = None
 904    ) -> typedefs.JSONObject:
 905        resp = await self._request(_GET, f"GroupV2/{id}", auth=access_token)
 906        assert isinstance(resp, dict)
 907        return resp
 908
 909    async def fetch_clan(
 910        self,
 911        name: str,
 912        /,
 913        access_token: str | None = None,
 914        *,
 915        type: enums.GroupType | int = enums.GroupType.CLAN,
 916    ) -> typedefs.JSONObject:
 917        resp = await self._request(
 918            _GET, f"GroupV2/Name/{name}/{int(type)}", auth=access_token
 919        )
 920        assert isinstance(resp, dict)
 921        return resp
 922
 923    async def search_group(
 924        self,
 925        name: str,
 926        group_type: enums.GroupType | int = enums.GroupType.CLAN,
 927        *,
 928        creation_date: clans.GroupDate | int = 0,
 929        sort_by: int | None = None,
 930        group_member_count_filter: typing.Literal[0, 1, 2, 3] | None = None,
 931        locale_filter: str | None = None,
 932        tag_text: str | None = None,
 933        items_per_page: int | None = None,
 934        current_page: int | None = None,
 935        request_token: str | None = None,
 936    ) -> typedefs.JSONObject:
 937        payload: collections.MutableMapping[str, typing.Any] = {"name": name}
 938
 939        # as the official documentation says, you're not allowed to use those fields
 940        # on a clan search. it is safe to send the request with them being `null` but not filled with a value.
 941        if (
 942            group_type == enums.GroupType.CLAN
 943            and group_member_count_filter is not None
 944            and locale_filter
 945            and tag_text
 946        ):
 947            raise ValueError(
 948                "If you're searching for clans, (group_member_count_filter, locale_filter, tag_text) must be None."
 949            )
 950
 951        payload["groupType"] = int(group_type)
 952        payload["creationDate"] = int(creation_date)
 953        payload["sortBy"] = sort_by
 954        payload["groupMemberCount"] = group_member_count_filter
 955        payload["locale"] = locale_filter
 956        payload["tagText"] = tag_text
 957        payload["itemsPerPage"] = items_per_page
 958        payload["currentPage"] = current_page
 959        payload["requestToken"] = request_token
 960        payload["requestContinuationToken"] = request_token
 961
 962        resp = await self._request(_POST, "GroupV2/Search/", json=payload)
 963        assert isinstance(resp, dict)
 964        return resp
 965
 966    async def fetch_clan_admins(self, clan_id: int, /) -> typedefs.JSONObject:
 967        resp = await self._request(_GET, f"GroupV2/{clan_id}/AdminsAndFounder/")
 968        assert isinstance(resp, dict)
 969        return resp
 970
 971    async def fetch_clan_conversations(self, clan_id: int, /) -> typedefs.JSONArray:
 972        resp = await self._request(_GET, f"GroupV2/{clan_id}/OptionalConversations/")
 973        assert isinstance(resp, list)
 974        return resp
 975
 976    async def fetch_application(self, appid: int, /) -> typedefs.JSONObject:
 977        resp = await self._request(_GET, f"App/Application/{appid}")
 978        assert isinstance(resp, dict)
 979        return resp
 980
 981    async def fetch_character(
 982        self,
 983        member_id: int,
 984        membership_type: enums.MembershipType | int,
 985        character_id: int,
 986        components: collections.Sequence[enums.ComponentType],
 987        auth: str | None = None,
 988    ) -> typedefs.JSONObject:
 989        collector = _collect_components(components)
 990        response = await self._request(
 991            _GET,
 992            f"Destiny2/{int(membership_type)}/Profile/{member_id}/"
 993            f"Character/{character_id}/?components={collector}",
 994            auth=auth,
 995        )
 996        assert isinstance(response, dict)
 997        return response
 998
 999    async def fetch_activities(
1000        self,
1001        member_id: int,
1002        character_id: int,
1003        mode: enums.GameMode | int,
1004        membership_type: enums.MembershipType | int = enums.MembershipType.ALL,
1005        *,
1006        page: int = 0,
1007        limit: int = 1,
1008    ) -> typedefs.JSONObject:
1009        resp = await self._request(
1010            _GET,
1011            f"Destiny2/{int(membership_type)}/Account/"
1012            f"{member_id}/Character/{character_id}/Stats/Activities"
1013            f"/?mode={int(mode)}&count={limit}&page={page}",
1014        )
1015        assert isinstance(resp, dict)
1016        return resp
1017
1018    async def fetch_vendor_sales(self) -> typedefs.JSONObject:
1019        resp = await self._request(
1020            _GET,
1021            f"Destiny2/Vendors/?components={int(enums.ComponentType.VENDOR_SALES)}",
1022        )
1023        assert isinstance(resp, dict)
1024        return resp
1025
1026    async def fetch_profile(
1027        self,
1028        membership_id: int,
1029        type: enums.MembershipType | int,
1030        components: collections.Sequence[enums.ComponentType],
1031        auth: str | None = None,
1032    ) -> typedefs.JSONObject:
1033        collector = _collect_components(components)
1034        response = await self._request(
1035            _GET,
1036            f"Destiny2/{int(type)}/Profile/{membership_id}/?components={collector}",
1037            auth=auth,
1038        )
1039        assert isinstance(response, dict)
1040        return response
1041
1042    async def fetch_entity(self, type: str, hash: int) -> typedefs.JSONObject:
1043        response = await self._request(_GET, route=f"Destiny2/Manifest/{type}/{hash}")
1044        assert isinstance(response, dict)
1045        return response
1046
1047    async def fetch_inventory_item(self, hash: int, /) -> typedefs.JSONObject:
1048        resp = await self.fetch_entity("DestinyInventoryItemDefinition", hash)
1049        assert isinstance(resp, dict)
1050        return resp
1051
1052    async def fetch_objective_entity(self, hash: int, /) -> typedefs.JSONObject:
1053        resp = await self.fetch_entity("DestinyObjectiveDefinition", hash)
1054        assert isinstance(resp, dict)
1055        return resp
1056
1057    async def fetch_groups_for_member(
1058        self,
1059        member_id: int,
1060        member_type: enums.MembershipType | int,
1061        /,
1062        *,
1063        filter: int = 0,
1064        group_type: enums.GroupType | int = enums.GroupType.CLAN,
1065    ) -> typedefs.JSONObject:
1066        resp = await self._request(
1067            _GET,
1068            f"GroupV2/User/{int(member_type)}/{member_id}/{filter}/{int(group_type)}/",
1069        )
1070        assert isinstance(resp, dict)
1071        return resp
1072
1073    async def fetch_potential_groups_for_member(
1074        self,
1075        member_id: int,
1076        member_type: enums.MembershipType | int,
1077        /,
1078        *,
1079        filter: int = 0,
1080        group_type: enums.GroupType | int = enums.GroupType.CLAN,
1081    ) -> typedefs.JSONObject:
1082        resp = await self._request(
1083            _GET,
1084            f"GroupV2/User/Potential/{int(member_type)}/{member_id}/{filter}/{int(group_type)}/",
1085        )
1086        assert isinstance(resp, dict)
1087        return resp
1088
1089    async def fetch_clan_members(
1090        self,
1091        clan_id: int,
1092        /,
1093        *,
1094        name: str | None = None,
1095        type: enums.MembershipType | int = enums.MembershipType.NONE,
1096    ) -> typedefs.JSONObject:
1097        resp = await self._request(
1098            _GET,
1099            f"/GroupV2/{clan_id}/Members/?memberType={int(type)}&nameSearch={name if name else ''}&currentpage=1",
1100        )
1101        assert isinstance(resp, dict)
1102        return resp
1103
1104    async def fetch_hardlinked_credentials(
1105        self,
1106        credential: int,
1107        type: enums.CredentialType | int = enums.CredentialType.STEAMID,
1108        /,
1109    ) -> typedefs.JSONObject:
1110        resp = await self._request(
1111            _GET,
1112            f"User/GetMembershipFromHardLinkedCredential/{int(type)}/{credential}/",
1113        )
1114        assert isinstance(resp, dict)
1115        return resp
1116
1117    async def fetch_user_credentials(
1118        self, access_token: str, membership_id: int, /
1119    ) -> typedefs.JSONArray:
1120        resp = await self._request(
1121            _GET,
1122            f"User/GetCredentialTypesForTargetAccount/{membership_id}",
1123            auth=access_token,
1124        )
1125        assert isinstance(resp, list)
1126        return resp
1127
1128    async def insert_socket_plug(
1129        self,
1130        action_token: str,
1131        /,
1132        instance_id: int,
1133        plug: builders.PlugSocketBuilder | collections.Mapping[str, int],
1134        character_id: int,
1135        membership_type: enums.MembershipType | int,
1136    ) -> typedefs.JSONObject:
1137        if isinstance(plug, builders.PlugSocketBuilder):
1138            plug = plug.collect()
1139
1140        body = {
1141            "actionToken": action_token,
1142            "itemInstanceId": instance_id,
1143            "plug": plug,
1144            "characterId": character_id,
1145            "membershipType": int(membership_type),
1146        }
1147        resp = await self._request(
1148            _POST, "Destiny2/Actions/Items/InsertSocketPlug", json=body
1149        )
1150        assert isinstance(resp, dict)
1151        return resp
1152
1153    async def insert_socket_plug_free(
1154        self,
1155        access_token: str,
1156        /,
1157        instance_id: int,
1158        plug: builders.PlugSocketBuilder | collections.Mapping[str, int],
1159        character_id: int,
1160        membership_type: enums.MembershipType | int,
1161    ) -> typedefs.JSONObject:
1162        if isinstance(plug, builders.PlugSocketBuilder):
1163            plug = plug.collect()
1164
1165        body = {
1166            "itemInstanceId": instance_id,
1167            "plug": plug,
1168            "characterId": character_id,
1169            "membershipType": int(membership_type),
1170        }
1171        resp = await self._request(
1172            _POST,
1173            "Destiny2/Actions/Items/InsertSocketPlugFree",
1174            json=body,
1175            auth=access_token,
1176        )
1177        assert isinstance(resp, dict)
1178        return resp
1179
1180    @helpers.unstable
1181    async def set_item_lock_state(
1182        self,
1183        access_token: str,
1184        state: bool,
1185        /,
1186        item_id: int,
1187        character_id: int,
1188        membership_type: enums.MembershipType | int,
1189    ) -> int:
1190        body = {
1191            "state": state,
1192            "itemId": item_id,
1193            "characterId": character_id,
1194            "membershipType": int(membership_type),
1195        }
1196        response = await self._request(
1197            _POST,
1198            "Destiny2/Actions/Items/SetLockState",
1199            json=body,
1200            auth=access_token,
1201        )
1202        assert isinstance(response, int)
1203        return response
1204
1205    async def set_quest_track_state(
1206        self,
1207        access_token: str,
1208        state: bool,
1209        /,
1210        item_id: int,
1211        character_id: int,
1212        membership_type: enums.MembershipType | int,
1213    ) -> int:
1214        body = {
1215            "state": state,
1216            "itemId": item_id,
1217            "characterId": character_id,
1218            "membership_type": int(membership_type),
1219        }
1220        response = await self._request(
1221            _POST,
1222            "Destiny2/Actions/Items/SetTrackedState",
1223            json=body,
1224            auth=access_token,
1225        )
1226        assert isinstance(response, int)
1227        return response
1228
1229    async def fetch_manifest_path(self) -> typedefs.JSONObject:
1230        path = await self._request(_GET, "Destiny2/Manifest")
1231        assert isinstance(path, dict)
1232        return path
1233
1234    async def read_manifest_bytes(self, language: _ALLOWED_LANGS = "en", /) -> bytes:
1235        _ensure_manifest_language(language)
1236
1237        content = await self.fetch_manifest_path()
1238        resp = await self._request(
1239            _GET,
1240            content["mobileWorldContentPaths"][language],
1241            unwrap_bytes=True,
1242            base=True,
1243        )
1244        assert isinstance(resp, bytes)
1245        return resp
1246
1247    async def download_sqlite_manifest(
1248        self,
1249        language: _ALLOWED_LANGS = "en",
1250        name: str = "manifest",
1251        path: pathlib.Path | str = ".",
1252        *,
1253        force: bool = False,
1254        executor: concurrent.futures.Executor | None = None,
1255    ) -> pathlib.Path:
1256        complete_path = _get_path(name, path, sql=True)
1257
1258        if complete_path.exists():
1259            if force:
1260                _LOGGER.info(
1261                    f"Found manifest in {complete_path!s}. Forcing to Re-Download."
1262                )
1263                complete_path.unlink(missing_ok=True)
1264
1265                return await self.download_sqlite_manifest(
1266                    language, name, path, force=force
1267                )
1268
1269            else:
1270                raise FileExistsError(
1271                    "Manifest file already exists, "
1272                    "To force download, set the `force` parameter to `True`."
1273                )
1274
1275        _LOGGER.info(f"Downloading manifest. Location: {complete_path!s}")
1276        data_bytes = await self.read_manifest_bytes(language)
1277        await asyncio.get_running_loop().run_in_executor(
1278            executor, _write_sqlite_bytes, data_bytes, path, name
1279        )
1280        _LOGGER.info("Finished downloading manifest.")
1281        return _get_path(name, path, sql=True)
1282
1283    async def download_json_manifest(
1284        self,
1285        file_name: str = "manifest",
1286        path: str | pathlib.Path = ".",
1287        *,
1288        language: _ALLOWED_LANGS = "en",
1289        executor: concurrent.futures.Executor | None = None,
1290    ) -> pathlib.Path:
1291        _ensure_manifest_language(language)
1292        full_path = _get_path(file_name, path)
1293        _LOGGER.info(f"Downloading manifest JSON to {full_path!r}...")
1294
1295        content = await self.fetch_manifest_path()
1296        json_bytes = await self._request(
1297            _GET,
1298            content["jsonWorldContentPaths"][language],
1299            unwrap_bytes=True,
1300            base=True,
1301        )
1302
1303        assert isinstance(json_bytes, bytes)
1304        await asyncio.get_running_loop().run_in_executor(
1305            executor, _write_json_bytes, json_bytes, file_name, path
1306        )
1307        _LOGGER.info("Finished downloading manifest JSON.")
1308        return full_path
1309
1310    async def fetch_manifest_version(self) -> str:
1311        # This is guaranteed str.
1312        return (await self.fetch_manifest_path())["version"]
1313
1314    async def fetch_linked_profiles(
1315        self,
1316        member_id: int,
1317        member_type: enums.MembershipType | int,
1318        /,
1319        *,
1320        all: bool = False,
1321    ) -> typedefs.JSONObject:
1322        resp = await self._request(
1323            _GET,
1324            f"Destiny2/{int(member_type)}/Profile/{member_id}/LinkedProfiles/?getAllMemberships={all}",
1325        )
1326        assert isinstance(resp, dict)
1327        return resp
1328
1329    async def fetch_clan_banners(self) -> typedefs.JSONObject:
1330        resp = await self._request(_GET, "Destiny2/Clan/ClanBannerDictionary/")
1331        assert isinstance(resp, dict)
1332        return resp
1333
1334    async def fetch_public_milestones(self) -> typedefs.JSONObject:
1335        resp = await self._request(_GET, "Destiny2/Milestones/")
1336        assert isinstance(resp, dict)
1337        return resp
1338
1339    async def fetch_public_milestone_content(
1340        self, milestone_hash: int, /
1341    ) -> typedefs.JSONObject:
1342        resp = await self._request(
1343            _GET, f"Destiny2/Milestones/{milestone_hash}/Content/"
1344        )
1345        assert isinstance(resp, dict)
1346        return resp
1347
1348    async def fetch_current_user_memberships(
1349        self, access_token: str, /
1350    ) -> typedefs.JSONObject:
1351        resp = await self._request(
1352            _GET,
1353            "User/GetMembershipsForCurrentUser/",
1354            auth=access_token,
1355        )
1356        assert isinstance(resp, dict)
1357        return resp
1358
1359    async def equip_item(
1360        self,
1361        access_token: str,
1362        /,
1363        item_id: int,
1364        character_id: int,
1365        membership_type: enums.MembershipType | int,
1366    ) -> None:
1367        payload = {
1368            "itemId": item_id,
1369            "characterId": character_id,
1370            "membershipType": int(membership_type),
1371        }
1372
1373        await self._request(
1374            _POST,
1375            "Destiny2/Actions/Items/EquipItem/",
1376            json=payload,
1377            auth=access_token,
1378        )
1379
1380    async def equip_items(
1381        self,
1382        access_token: str,
1383        /,
1384        item_ids: collections.Sequence[int],
1385        character_id: int,
1386        membership_type: enums.MembershipType | int,
1387    ) -> None:
1388        payload = {
1389            "itemIds": item_ids,
1390            "characterId": character_id,
1391            "membershipType": int(membership_type),
1392        }
1393        await self._request(
1394            _POST,
1395            "Destiny2/Actions/Items/EquipItems/",
1396            json=payload,
1397            auth=access_token,
1398        )
1399
1400    async def ban_clan_member(
1401        self,
1402        access_token: str,
1403        /,
1404        group_id: int,
1405        membership_id: int,
1406        membership_type: enums.MembershipType | int,
1407        *,
1408        length: int = 0,
1409        comment: str | None = None,
1410    ) -> None:
1411        payload = {"comment": str(comment), "length": length}
1412        await self._request(
1413            _POST,
1414            f"GroupV2/{group_id}/Members/{int(membership_type)}/{membership_id}/Ban/",
1415            json=payload,
1416            auth=access_token,
1417        )
1418
1419    async def unban_clan_member(
1420        self,
1421        access_token: str,
1422        /,
1423        group_id: int,
1424        membership_id: int,
1425        membership_type: enums.MembershipType | int,
1426    ) -> None:
1427        await self._request(
1428            _POST,
1429            f"GroupV2/{group_id}/Members/{int(membership_type)}/{membership_id}/Unban/",
1430            auth=access_token,
1431        )
1432
1433    async def kick_clan_member(
1434        self,
1435        access_token: str,
1436        /,
1437        group_id: int,
1438        membership_id: int,
1439        membership_type: enums.MembershipType | int,
1440    ) -> typedefs.JSONObject:
1441        resp = await self._request(
1442            _POST,
1443            f"GroupV2/{group_id}/Members/{int(membership_type)}/{membership_id}/Kick/",
1444            auth=access_token,
1445        )
1446        assert isinstance(resp, dict)
1447        return resp
1448
1449    async def edit_clan(
1450        self,
1451        access_token: str,
1452        /,
1453        group_id: int,
1454        *,
1455        name: str | None = None,
1456        about: str | None = None,
1457        motto: str | None = None,
1458        theme: str | None = None,
1459        tags: collections.Sequence[str] | None = None,
1460        is_public: bool | None = None,
1461        locale: str | None = None,
1462        avatar_image_index: int | None = None,
1463        membership_option: enums.MembershipOption | int | None = None,
1464        allow_chat: bool | None = None,
1465        chat_security: typing.Literal[0, 1] | None = None,
1466        call_sign: str | None = None,
1467        homepage: typing.Literal[0, 1, 2] | None = None,
1468        enable_invite_messaging_for_admins: bool | None = None,
1469        default_publicity: typing.Literal[0, 1, 2] | None = None,
1470        is_public_topic_admin: bool | None = None,
1471    ) -> None:
1472        payload = {
1473            "name": name,
1474            "about": about,
1475            "motto": motto,
1476            "theme": theme,
1477            "tags": tags,
1478            "isPublic": is_public,
1479            "avatarImageIndex": avatar_image_index,
1480            "isPublicTopicAdminOnly": is_public_topic_admin,
1481            "allowChat": allow_chat,
1482            "chatSecurity": chat_security,
1483            "callsign": call_sign,
1484            "homepage": homepage,
1485            "enableInvitationMessagingForAdmins": enable_invite_messaging_for_admins,
1486            "defaultPublicity": default_publicity,
1487            "locale": locale,
1488        }
1489        if membership_option is not None:
1490            payload["membershipOption"] = int(membership_option)
1491
1492        await self._request(
1493            _POST,
1494            f"GroupV2/{group_id}/Edit",
1495            json=payload,
1496            auth=access_token,
1497        )
1498
1499    async def edit_clan_options(
1500        self,
1501        access_token: str,
1502        /,
1503        group_id: int,
1504        *,
1505        invite_permissions_override: bool | None = None,
1506        update_culture_permissionOverride: bool | None = None,
1507        host_guided_game_permission_override: typing.Literal[0, 1, 2] | None = None,
1508        update_banner_permission_override: bool | None = None,
1509        join_level: enums.ClanMemberType | int | None = None,
1510    ) -> None:
1511        payload = {
1512            "InvitePermissionOverride": invite_permissions_override,
1513            "UpdateCulturePermissionOverride": update_culture_permissionOverride,
1514            "HostGuidedGamePermissionOverride": host_guided_game_permission_override,
1515            "UpdateBannerPermissionOverride": update_banner_permission_override,
1516            "JoinLevel": int(join_level) if join_level else None,
1517        }
1518
1519        await self._request(
1520            _POST,
1521            f"GroupV2/{group_id}/EditFounderOptions",
1522            json=payload,
1523            auth=access_token,
1524        )
1525
1526    async def report_player(
1527        self,
1528        access_token: str,
1529        /,
1530        activity_id: int,
1531        character_id: int,
1532        reason_hashes: collections.Sequence[int],
1533        reason_category_hashes: collections.Sequence[int],
1534    ) -> None:
1535        await self._request(
1536            _POST,
1537            f"Destiny2/Stats/PostGameCarnageReport/{activity_id}/Report/",
1538            json={
1539                "reasonCategoryHashes": reason_category_hashes,
1540                "reasonHashes": reason_hashes,
1541                "offendingCharacterId": character_id,
1542            },
1543            auth=access_token,
1544        )
1545
1546    async def fetch_friends(self, access_token: str, /) -> typedefs.JSONObject:
1547        resp = await self._request(
1548            _GET,
1549            "Social/Friends/",
1550            auth=access_token,
1551        )
1552        assert isinstance(resp, dict)
1553        return resp
1554
1555    async def fetch_friend_requests(self, access_token: str, /) -> typedefs.JSONObject:
1556        resp = await self._request(
1557            _GET,
1558            "Social/Friends/Requests",
1559            auth=access_token,
1560        )
1561        assert isinstance(resp, dict)
1562        return resp
1563
1564    async def accept_friend_request(self, access_token: str, /, member_id: int) -> None:
1565        await self._request(
1566            _POST,
1567            f"Social/Friends/Requests/Accept/{member_id}",
1568            auth=access_token,
1569        )
1570
1571    async def send_friend_request(self, access_token: str, /, member_id: int) -> None:
1572        await self._request(
1573            _POST,
1574            f"Social/Friends/Add/{member_id}",
1575            auth=access_token,
1576        )
1577
1578    async def decline_friend_request(
1579        self, access_token: str, /, member_id: int
1580    ) -> None:
1581        await self._request(
1582            _POST,
1583            f"Social/Friends/Requests/Decline/{member_id}",
1584            auth=access_token,
1585        )
1586
1587    async def remove_friend(self, access_token: str, /, member_id: int) -> None:
1588        await self._request(
1589            _POST,
1590            f"Social/Friends/Remove/{member_id}",
1591            auth=access_token,
1592        )
1593
1594    async def remove_friend_request(self, access_token: str, /, member_id: int) -> None:
1595        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1596        await self._request(
1597            _POST,
1598            f"Social/Friends/Requests/Remove/{member_id}",
1599            auth=access_token,
1600        )
1601
1602    async def approve_all_pending_group_users(
1603        self,
1604        access_token: str,
1605        /,
1606        group_id: int,
1607        message: str | None = None,
1608    ) -> None:
1609        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1610        await self._request(
1611            _POST,
1612            f"GroupV2/{group_id}/Members/ApproveAll",
1613            auth=access_token,
1614            json={"message": str(message)},
1615        )
1616
1617    async def deny_all_pending_group_users(
1618        self,
1619        access_token: str,
1620        /,
1621        group_id: int,
1622        *,
1623        message: str | None = None,
1624    ) -> None:
1625        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1626        await self._request(
1627            _POST,
1628            f"GroupV2/{group_id}/Members/DenyAll",
1629            auth=access_token,
1630            json={"message": str(message)},
1631        )
1632
1633    async def add_optional_conversation(
1634        self,
1635        access_token: str,
1636        /,
1637        group_id: int,
1638        *,
1639        name: str | None = None,
1640        security: typing.Literal[0, 1] = 0,
1641    ) -> None:
1642        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1643        payload = {"chatName": str(name), "chatSecurity": security}
1644        await self._request(
1645            _POST,
1646            f"GroupV2/{group_id}/OptionalConversations/Add",
1647            json=payload,
1648            auth=access_token,
1649        )
1650
1651    async def edit_optional_conversation(
1652        self,
1653        access_token: str,
1654        /,
1655        group_id: int,
1656        conversation_id: int,
1657        *,
1658        name: str | None = None,
1659        security: typing.Literal[0, 1] = 0,
1660        enable_chat: bool = False,
1661    ) -> None:
1662        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1663        payload = {
1664            "chatEnabled": enable_chat,
1665            "chatName": str(name),
1666            "chatSecurity": security,
1667        }
1668        await self._request(
1669            _POST,
1670            f"GroupV2/{group_id}/OptionalConversations/Edit/{conversation_id}",
1671            json=payload,
1672            auth=access_token,
1673        )
1674
1675    async def transfer_item(
1676        self,
1677        access_token: str,
1678        /,
1679        item_id: int,
1680        item_hash: int,
1681        character_id: int,
1682        member_type: enums.MembershipType | int,
1683        *,
1684        stack_size: int = 1,
1685        vault: bool = False,
1686    ) -> None:
1687        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1688        payload = {
1689            "characterId": character_id,
1690            "membershipType": int(member_type),
1691            "itemId": item_id,
1692            "itemReferenceHash": item_hash,
1693            "stackSize": stack_size,
1694            "transferToVault": vault,
1695        }
1696        await self._request(
1697            _POST,
1698            "Destiny2/Actions/Items/TransferItem",
1699            json=payload,
1700            auth=access_token,
1701        )
1702
1703    async def pull_item(
1704        self,
1705        access_token: str,
1706        /,
1707        item_id: int,
1708        item_hash: int,
1709        character_id: int,
1710        member_type: enums.MembershipType | int,
1711        *,
1712        stack_size: int = 1,
1713        vault: bool = False,
1714    ) -> None:
1715        # <<inherited docstring from aiobungie.interfaces.rest.RESTInterface>>
1716        payload = {
1717            "characterId": character_id,
1718            "membershipType": int(member_type),
1719            "itemId": item_id,
1720            "itemReferenceHash": item_hash,
1721            "stackSize": stack_size,
1722        }
1723        await self._request(
1724            _POST,
1725            "Destiny2/Actions/Items/PullFromPostmaster",
1726            json=payload,
1727            auth=access_token,
1728        )
1729        if vault:
1730            await self.transfer_item(
1731                access_token,
1732                item_id=item_id,
1733                item_hash=item_hash,
1734                character_id=character_id,
1735                member_type=member_type,
1736                stack_size=stack_size,
1737                vault=True,
1738            )
1739
1740    async def fetch_fireteams(
1741        self,
1742        activity_type: fireteams.FireteamActivity | int,
1743        *,
1744        platform: fireteams.FireteamPlatform | int = fireteams.FireteamPlatform.ANY,
1745        language: fireteams.FireteamLanguage | str = fireteams.FireteamLanguage.ALL,
1746        date_range: fireteams.FireteamDate | int = fireteams.FireteamDate.ALL,
1747        page: int = 0,
1748        slots_filter: int = 0,
1749    ) -> typedefs.JSONObject:
1750        resp = await self._request(
1751            _GET,
1752            f"Fireteam/Search/Available/{int(platform)}/{int(activity_type)}/{int(date_range)}/{slots_filter}/{page}/?langFilter={str(language)}",  # noqa: E501 Line too long
1753        )
1754        assert isinstance(resp, dict)
1755        return resp
1756
1757    async def fetch_available_clan_fireteams(
1758        self,
1759        access_token: str,
1760        group_id: int,
1761        activity_type: fireteams.FireteamActivity | int,
1762        *,
1763        platform: fireteams.FireteamPlatform | int,
1764        language: fireteams.FireteamLanguage | str,
1765        date_range: fireteams.FireteamDate | int = fireteams.FireteamDate.ALL,
1766        page: int = 0,
1767        public_only: bool = False,
1768        slots_filter: int = 0,
1769    ) -> typedefs.JSONObject:
1770        resp = await self._request(
1771            _GET,
1772            f"Fireteam/Clan/{group_id}/Available/{int(platform)}/{int(activity_type)}/{int(date_range)}/{slots_filter}/{public_only}/{page}",  # noqa: E501
1773            json={"langFilter": str(language)},
1774            auth=access_token,
1775        )
1776        assert isinstance(resp, dict)
1777        return resp
1778
1779    async def fetch_clan_fireteam(
1780        self, access_token: str, fireteam_id: int, group_id: int
1781    ) -> typedefs.JSONObject:
1782        resp = await self._request(
1783            _GET,
1784            f"Fireteam/Clan/{group_id}/Summary/{fireteam_id}",
1785            auth=access_token,
1786        )
1787        assert isinstance(resp, dict)
1788        return resp
1789
1790    async def fetch_my_clan_fireteams(
1791        self,
1792        access_token: str,
1793        group_id: int,
1794        *,
1795        include_closed: bool = True,
1796        platform: fireteams.FireteamPlatform | int,
1797        language: fireteams.FireteamLanguage | str,
1798        filtered: bool = True,
1799        page: int = 0,
1800    ) -> typedefs.JSONObject:
1801        payload = {"groupFilter": filtered, "langFilter": str(language)}
1802
1803        resp = await self._request(
1804            _GET,
1805            f"Fireteam/Clan/{group_id}/My/{int(platform)}/{include_closed}/{page}",
1806            json=payload,
1807            auth=access_token,
1808        )
1809        assert isinstance(resp, dict)
1810        return resp
1811
1812    async def fetch_private_clan_fireteams(
1813        self, access_token: str, group_id: int, /
1814    ) -> int:
1815        resp = await self._request(
1816            _GET,
1817            f"Fireteam/Clan/{group_id}/ActiveCount",
1818            auth=access_token,
1819        )
1820        assert isinstance(resp, int)
1821        return resp
1822
1823    async def fetch_post_activity(self, instance_id: int, /) -> typedefs.JSONObject:
1824        resp = await self._request(
1825            _GET, f"Destiny2/Stats/PostGameCarnageReport/{instance_id}"
1826        )
1827        assert isinstance(resp, dict)
1828        return resp
1829
1830    @helpers.unstable
1831    async def search_entities(
1832        self, name: str, entity_type: str, *, page: int = 0
1833    ) -> typedefs.JSONObject:
1834        resp = await self._request(
1835            _GET,
1836            f"Destiny2/Armory/Search/{entity_type}/{name}/",
1837            json={"page": page},
1838        )
1839        assert isinstance(resp, dict)
1840        return resp
1841
1842    async def fetch_unique_weapon_history(
1843        self,
1844        membership_id: int,
1845        character_id: int,
1846        membership_type: enums.MembershipType | int,
1847    ) -> typedefs.JSONObject:
1848        resp = await self._request(
1849            _GET,
1850            f"Destiny2/{int(membership_type)}/Account/{membership_id}/Character/{character_id}/Stats/UniqueWeapons/",
1851        )
1852        assert isinstance(resp, dict)
1853        return resp
1854
1855    async def fetch_item(
1856        self,
1857        member_id: int,
1858        item_id: int,
1859        membership_type: enums.MembershipType | int,
1860        components: collections.Sequence[enums.ComponentType],
1861    ) -> typedefs.JSONObject:
1862        collector = _collect_components(components)
1863
1864        resp = await self._request(
1865            _GET,
1866            f"Destiny2/{int(membership_type)}/Profile/{member_id}/Item/{item_id}/?components={collector}",
1867        )
1868        assert isinstance(resp, dict)
1869        return resp
1870
1871    async def fetch_clan_weekly_rewards(self, clan_id: int, /) -> typedefs.JSONObject:
1872        resp = await self._request(_GET, f"Destiny2/Clan/{clan_id}/WeeklyRewardState/")
1873        assert isinstance(resp, dict)
1874        return resp
1875
1876    async def fetch_available_locales(self) -> typedefs.JSONObject:
1877        resp = await self._request(_GET, "Destiny2/Manifest/DestinyLocaleDefinition/")
1878        assert isinstance(resp, dict)
1879        return resp
1880
1881    async def fetch_common_settings(self) -> typedefs.JSONObject:
1882        resp = await self._request(_GET, "Settings")
1883        assert isinstance(resp, dict)
1884        return resp
1885
1886    async def fetch_user_systems_overrides(self) -> typedefs.JSONObject:
1887        resp = await self._request(_GET, "UserSystemOverrides")
1888        assert isinstance(resp, dict)
1889        return resp
1890
1891    async def fetch_global_alerts(
1892        self, *, include_streaming: bool = False
1893    ) -> typedefs.JSONArray:
1894        resp = await self._request(
1895            _GET, f"GlobalAlerts/?includestreaming={include_streaming}"
1896        )
1897        assert isinstance(resp, list)
1898        return resp
1899
1900    async def awainitialize_request(
1901        self,
1902        access_token: str,
1903        type: typing.Literal[0, 1],
1904        membership_type: enums.MembershipType | int,
1905        /,
1906        *,
1907        affected_item_id: int | None = None,
1908        character_id: int | None = None,
1909    ) -> typedefs.JSONObject:
1910        body = {"type": type, "membershipType": int(membership_type)}
1911
1912        if affected_item_id is not None:
1913            body["affectedItemId"] = affected_item_id
1914
1915        if character_id is not None:
1916            body["characterId"] = character_id
1917
1918        resp = await self._request(
1919            _POST, "Destiny2/Awa/Initialize", json=body, auth=access_token
1920        )
1921        assert isinstance(resp, dict)
1922        return resp
1923
1924    async def awaget_action_token(
1925        self, access_token: str, correlation_id: str, /
1926    ) -> typedefs.JSONObject:
1927        resp = await self._request(
1928            _POST,
1929            f"Destiny2/Awa/GetActionToken/{correlation_id}",
1930            auth=access_token,
1931        )
1932        assert isinstance(resp, dict)
1933        return resp
1934
1935    async def awa_provide_authorization_result(
1936        self,
1937        access_token: str,
1938        selection: int,
1939        correlation_id: str,
1940        nonce: collections.MutableSequence[str | bytes],
1941    ) -> int:
1942        body = {"selection": selection, "correlationId": correlation_id, "nonce": nonce}
1943
1944        resp = await self._request(
1945            _POST,
1946            "Destiny2/Awa/AwaProvideAuthorizationResult",
1947            json=body,
1948            auth=access_token,
1949        )
1950        assert isinstance(resp, int)
1951        return resp
1952
1953    async def fetch_vendors(
1954        self,
1955        access_token: str,
1956        character_id: int,
1957        membership_id: int,
1958        membership_type: enums.MembershipType | int,
1959        /,
1960        components: collections.Sequence[enums.ComponentType],
1961        filter: int | None = None,
1962    ) -> typedefs.JSONObject:
1963        components_ = _collect_components(components)
1964        route = (
1965            f"Destiny2/{int(membership_type)}/Profile/{membership_id}"
1966            f"/Character/{character_id}/Vendors/?components={components_}"
1967        )
1968
1969        if filter is not None:
1970            route = route + f"&filter={filter}"
1971
1972        resp = await self._request(
1973            _GET,
1974            route,
1975            auth=access_token,
1976        )
1977        assert isinstance(resp, dict)
1978        return resp
1979
1980    async def fetch_vendor(
1981        self,
1982        access_token: str,
1983        character_id: int,
1984        membership_id: int,
1985        membership_type: enums.MembershipType | int,
1986        vendor_hash: int,
1987        /,
1988        components: collections.Sequence[enums.ComponentType],
1989    ) -> typedefs.JSONObject:
1990        components_ = _collect_components(components)
1991        resp = await self._request(
1992            _GET,
1993            (
1994                f"Destiny2/{int(membership_type)}/Profile/{membership_id}"
1995                f"/Character/{character_id}/Vendors/{vendor_hash}/?components={components_}"
1996            ),
1997            auth=access_token,
1998        )
1999        assert isinstance(resp, dict)
2000        return resp
2001
2002    async def fetch_application_api_usage(
2003        self,
2004        access_token: str,
2005        application_id: int,
2006        /,
2007        *,
2008        start: datetime.datetime | None = None,
2009        end: datetime.datetime | None = None,
2010    ) -> typedefs.JSONObject:
2011        end_date, start_date = time.parse_date_range(end, start)
2012        resp = await self._request(
2013            _GET,
2014            f"App/ApiUsage/{application_id}/?end={end_date}&start={start_date}",
2015            auth=access_token,
2016        )
2017        assert isinstance(resp, dict)
2018        return resp
2019
2020    async def fetch_bungie_applications(self) -> typedefs.JSONArray:
2021        resp = await self._request(_GET, "App/FirstParty")
2022        assert isinstance(resp, list)
2023        return resp
2024
2025    async def fetch_content_type(self, type: str, /) -> typedefs.JSONObject:
2026        resp = await self._request(_GET, f"Content/GetContentType/{type}/")
2027        assert isinstance(resp, dict)
2028        return resp
2029
2030    async def fetch_content_by_id(
2031        self, id: int, locale: str, /, *, head: bool = False
2032    ) -> typedefs.JSONObject:
2033        resp = await self._request(
2034            _GET,
2035            f"Content/GetContentById/{id}/{locale}/",
2036            json={"head": head},
2037        )
2038        assert isinstance(resp, dict)
2039        return resp
2040
2041    async def fetch_content_by_tag_and_type(
2042        self, locale: str, tag: str, type: str, *, head: bool = False
2043    ) -> typedefs.JSONObject:
2044        resp = await self._request(
2045            _GET,
2046            f"Content/GetContentByTagAndType/{tag}/{type}/{locale}/",
2047            json={"head": head},
2048        )
2049        assert isinstance(resp, dict)
2050        return resp
2051
2052    async def search_content_with_text(
2053        self,
2054        locale: str,
2055        /,
2056        content_type: str,
2057        search_text: str,
2058        tag: str,
2059        *,
2060        page: int | None = None,
2061        source: str | None = None,
2062    ) -> typedefs.JSONObject:
2063        body: typedefs.JSONObject = {
2064            "locale": locale,
2065            "currentpage": page or 1,
2066            "ctype": content_type,
2067            "searchtxt": search_text,
2068            "searchtext": search_text,
2069            "tag": tag,
2070            "source": source,
2071        }
2072
2073        resp = await self._request(_GET, "Content/Search", params=body)
2074        assert isinstance(resp, dict)
2075        return resp
2076
2077    async def search_content_by_tag_and_type(
2078        self,
2079        locale: str,
2080        tag: str,
2081        type: str,
2082        *,
2083        page: int | None = None,
2084    ) -> typedefs.JSONObject:
2085        body: typedefs.JSONObject = {"currentpage": page or 1}
2086
2087        resp = await self._request(
2088            _GET,
2089            f"Content/SearchContentByTagAndType/{tag}/{type}/{locale}/",
2090            params=body,
2091        )
2092        assert isinstance(resp, dict)
2093        return resp
2094
2095    async def search_help_articles(
2096        self, text: str, size: str, /
2097    ) -> typedefs.JSONObject:
2098        resp = await self._request(_GET, f"Content/SearchHelpArticles/{text}/{size}/")
2099        assert isinstance(resp, dict)
2100        return resp
2101
2102    async def fetch_topics_page(
2103        self,
2104        category_filter: int,
2105        group: int,
2106        date_filter: int,
2107        sort: str | bytes,
2108        *,
2109        page: int | None = None,
2110        locales: collections.Iterable[str] | None = None,
2111        tag_filter: str | None = None,
2112    ) -> typedefs.JSONObject:
2113        params = {
2114            "locales": ",".join(locales) if locales is not None else "en",
2115        }
2116        if tag_filter:
2117            params["tagstring"] = tag_filter
2118
2119        resp = await self._request(
2120            _GET,
2121            f"Forum/GetTopicsPaged/{page or 0}/0/{group}/{sort!s}/{date_filter}/{category_filter}/",
2122            params=params,
2123        )
2124        assert isinstance(resp, dict)
2125        return resp
2126
2127    async def fetch_core_topics_page(
2128        self,
2129        category_filter: int,
2130        date_filter: int,
2131        sort: str | bytes,
2132        *,
2133        page: int | None = None,
2134        locales: collections.Iterable[str] | None = None,
2135    ) -> typedefs.JSONObject:
2136        resp = await self._request(
2137            _GET,
2138            f"Forum/GetCoreTopicsPaged/{page or 0}"
2139            f"/{sort!s}/{date_filter}/{category_filter}/?locales={','.join(locales) if locales else 'en'}",
2140        )
2141        assert isinstance(resp, dict)
2142        return resp
2143
2144    async def fetch_posts_threaded_page(
2145        self,
2146        parent_post: bool,
2147        page: int,
2148        page_size: int,
2149        parent_post_id: int,
2150        reply_size: int,
2151        root_thread_mode: bool,
2152        sort_mode: int,
2153        show_banned: str | None = None,
2154    ) -> typedefs.JSONObject:
2155        resp = await self._request(
2156            _GET,
2157            f"Forum/GetPostsThreadedPaged/{parent_post}/{page}/"
2158            f"{page_size}/{reply_size}/{parent_post_id}/{root_thread_mode}/{sort_mode}/",
2159            json={"showbanned": show_banned},
2160        )
2161        assert isinstance(resp, dict)
2162        return resp
2163
2164    async def fetch_posts_threaded_page_from_child(
2165        self,
2166        child_id: bool,
2167        page: int,
2168        page_size: int,
2169        reply_size: int,
2170        root_thread_mode: bool,
2171        sort_mode: int,
2172        show_banned: str | None = None,
2173    ) -> typedefs.JSONObject:
2174        resp = await self._request(
2175            _GET,
2176            f"Forum/GetPostsThreadedPagedFromChild/{child_id}/"
2177            f"{page}/{page_size}/{reply_size}/{root_thread_mode}/{sort_mode}/",
2178            json={"showbanned": show_banned},
2179        )
2180        assert isinstance(resp, dict)
2181        return resp
2182
2183    async def fetch_post_and_parent(
2184        self, child_id: int, /, *, show_banned: str | None = None
2185    ) -> typedefs.JSONObject:
2186        resp = await self._request(
2187            _GET,
2188            f"Forum/GetPostAndParent/{child_id}/",
2189            json={"showbanned": show_banned},
2190        )
2191        assert isinstance(resp, dict)
2192        return resp
2193
2194    async def fetch_posts_and_parent_awaiting(
2195        self, child_id: int, /, *, show_banned: str | None = None
2196    ) -> typedefs.JSONObject:
2197        resp = await self._request(
2198            _GET,
2199            f"Forum/GetPostAndParentAwaitingApproval/{child_id}/",
2200            json={"showbanned": show_banned},
2201        )
2202        assert isinstance(resp, dict)
2203        return resp
2204
2205    async def fetch_topic_for_content(self, content_id: int, /) -> int:
2206        resp = await self._request(_GET, f"Forum/GetTopicForContent/{content_id}/")
2207        assert isinstance(resp, int)
2208        return resp
2209
2210    async def fetch_forum_tag_suggestions(
2211        self, partial_tag: str, /
2212    ) -> typedefs.JSONObject:
2213        resp = await self._request(
2214            _GET,
2215            "Forum/GetForumTagSuggestions/",
2216            json={"partialtag": partial_tag},
2217        )
2218        assert isinstance(resp, dict)
2219        return resp
2220
2221    async def fetch_poll(self, topic_id: int, /) -> typedefs.JSONObject:
2222        resp = await self._request(_GET, f"Forum/Poll/{topic_id}/")
2223        assert isinstance(resp, dict)
2224        return resp
2225
2226    async def fetch_recruitment_thread_summaries(self) -> typedefs.JSONArray:
2227        resp = await self._request(_POST, "Forum/Recruit/Summaries/")
2228        assert isinstance(resp, list)
2229        return resp
2230
2231    async def fetch_recommended_groups(
2232        self,
2233        access_token: str,
2234        /,
2235        *,
2236        date_range: int = 0,
2237        group_type: enums.GroupType | int = enums.GroupType.CLAN,
2238    ) -> typedefs.JSONArray:
2239        resp = await self._request(
2240            _POST,
2241            f"GroupV2/Recommended/{int(group_type)}/{date_range}/",
2242            auth=access_token,
2243        )
2244        assert isinstance(resp, list)
2245        return resp
2246
2247    async def fetch_available_avatars(self) -> collections.Mapping[str, int]:
2248        resp = await self._request(_GET, "GroupV2/GetAvailableAvatars/")
2249        assert isinstance(resp, dict)
2250        return resp
2251
2252    async def fetch_user_clan_invite_setting(
2253        self,
2254        access_token: str,
2255        /,
2256        membership_type: enums.MembershipType | int,
2257    ) -> bool:
2258        resp = await self._request(
2259            _GET,
2260            f"GroupV2/GetUserClanInviteSetting/{int(membership_type)}/",
2261            auth=access_token,
2262        )
2263        assert isinstance(resp, bool)
2264        return resp
2265
2266    async def fetch_banned_group_members(
2267        self, access_token: str, group_id: int, /, *, page: int = 1
2268    ) -> typedefs.JSONObject:
2269        resp = await self._request(
2270            _GET,
2271            f"GroupV2/{group_id}/Banned/?currentpage={page}",
2272            auth=access_token,
2273        )
2274        assert isinstance(resp, dict)
2275        return resp
2276
2277    async def fetch_pending_group_memberships(
2278        self, access_token: str, group_id: int, /, *, current_page: int = 1
2279    ) -> typedefs.JSONObject:
2280        resp = await self._request(
2281            _GET,
2282            f"GroupV2/{group_id}/Members/Pending/?currentpage={current_page}",
2283            auth=access_token,
2284        )
2285        assert isinstance(resp, dict)
2286        return resp
2287
2288    async def fetch_invited_group_memberships(
2289        self, access_token: str, group_id: int, /, *, current_page: int = 1
2290    ) -> typedefs.JSONObject:
2291        resp = await self._request(
2292            _GET,
2293            f"GroupV2/{group_id}/Members/InvitedIndividuals/?currentpage={current_page}",
2294            auth=access_token,
2295        )
2296        assert isinstance(resp, dict)
2297        return resp
2298
2299    async def invite_member_to_group(
2300        self,
2301        access_token: str,
2302        /,
2303        group_id: int,
2304        membership_id: int,
2305        membership_type: enums.MembershipType | int,
2306        *,
2307        message: str | None = None,
2308    ) -> typedefs.JSONObject:
2309        resp = await self._request(
2310            _POST,
2311            f"GroupV2/{group_id}/Members/IndividualInvite/{int(membership_type)}/{membership_id}/",
2312            auth=access_token,
2313            json={"message": str(message)},
2314        )
2315        assert isinstance(resp, dict)
2316        return resp
2317
2318    async def cancel_group_member_invite(
2319        self,
2320        access_token: str,
2321        /,
2322        group_id: int,
2323        membership_id: int,
2324        membership_type: enums.MembershipType | int,
2325    ) -> typedefs.JSONObject:
2326        resp = await self._request(
2327            _POST,
2328            f"GroupV2/{group_id}/Members/IndividualInviteCancel/{int(membership_type)}/{membership_id}/",
2329            auth=access_token,
2330        )
2331        assert isinstance(resp, dict)
2332        return resp
2333
2334    async def fetch_historical_definition(self) -> typedefs.JSONObject:
2335        resp = await self._request(_GET, "Destiny2/Stats/Definition/")
2336        assert isinstance(resp, dict)
2337        return resp
2338
2339    async def fetch_historical_stats(
2340        self,
2341        character_id: int,
2342        membership_id: int,
2343        membership_type: enums.MembershipType | int,
2344        day_start: datetime.datetime,
2345        day_end: datetime.datetime,
2346        groups: collections.Sequence[enums.StatsGroupType | int],
2347        modes: collections.Sequence[enums.GameMode | int],
2348        *,
2349        period_type: enums.PeriodType = enums.PeriodType.ALL_TIME,
2350    ) -> typedefs.JSONObject:
2351        end, start = time.parse_date_range(day_end, day_start)
2352        resp = await self._request(
2353            _GET,
2354            f"Destiny2/{int(membership_type)}/Account/{membership_id}/Character/{character_id}/Stats/",
2355            json={
2356                "dayend": end,
2357                "daystart": start,
2358                "groups": [str(int(group)) for group in groups],
2359                "modes": [str(int(mode)) for mode in modes],
2360                "periodType": int(period_type),
2361            },
2362        )
2363        assert isinstance(resp, dict)
2364        return resp
2365
2366    async def fetch_historical_stats_for_account(
2367        self,
2368        membership_id: int,
2369        membership_type: enums.MembershipType | int,
2370        groups: collections.Sequence[enums.StatsGroupType | int],
2371    ) -> typedefs.JSONObject:
2372        resp = await self._request(
2373            _GET,
2374            f"Destiny2/{int(membership_type)}/Account/{membership_id}/Stats/",
2375            json={"groups": [str(int(group)) for group in groups]},
2376        )
2377        assert isinstance(resp, dict)
2378        return resp
2379
2380    async def fetch_aggregated_activity_stats(
2381        self,
2382        character_id: int,
2383        membership_id: int,
2384        membership_type: enums.MembershipType | int,
2385        /,
2386    ) -> typedefs.JSONObject:
2387        resp = await self._request(
2388            _GET,
2389            f"Destiny2/{int(membership_type)}/Account/{membership_id}/"
2390            f"Character/{character_id}/Stats/AggregateActivityStats/",
2391        )
2392        assert isinstance(resp, dict)
2393        return resp
2394
2395    async def equip_loadout(
2396        self,
2397        access_token: str,
2398        /,
2399        loadout_index: int,
2400        character_id: int,
2401        membership_type: enums.MembershipType | int,
2402    ) -> None:
2403        response = await self._request(
2404            _POST,
2405            "Destiny2/Actions/Loadouts/EquipLoadout/",
2406            json={
2407                "loadoutIndex": loadout_index,
2408                "characterId": character_id,
2409                "membership_type": int(membership_type),
2410            },
2411            auth=access_token,
2412        )
2413        assert isinstance(response, int)
2414
2415    async def snapshot_loadout(
2416        self,
2417        access_token: str,
2418        /,
2419        loadout_index: int,
2420        character_id: int,
2421        membership_type: enums.MembershipType | int,
2422        *,
2423        color_hash: int | None = None,
2424        icon_hash: int | None = None,
2425        name_hash: int | None = None,
2426    ) -> None:
2427        response = await self._request(
2428            _POST,
2429            "Destiny2/Actions/Loadouts/SnapshotLoadout/",
2430            auth=access_token,
2431            json={
2432                "colorHash": color_hash,
2433                "iconHash": icon_hash,
2434                "nameHash": name_hash,
2435                "loadoutIndex": loadout_index,
2436                "characterId": character_id,
2437                "membershipType": int(membership_type),
2438            },
2439        )
2440        assert isinstance(response, int)
2441
2442    async def update_loadout(
2443        self,
2444        access_token: str,
2445        /,
2446        loadout_index: int,
2447        character_id: int,
2448        membership_type: enums.MembershipType | int,
2449        *,
2450        color_hash: int | None = None,
2451        icon_hash: int | None = None,
2452        name_hash: int | None = None,
2453    ) -> None:
2454        response = await self._request(
2455            _POST,
2456            "Destiny2/Actions/Loadouts/UpdateLoadoutIdentifiers/",
2457            auth=access_token,
2458            json={
2459                "colorHash": color_hash,
2460                "iconHash": icon_hash,
2461                "nameHash": name_hash,
2462                "loadoutIndex": loadout_index,
2463                "characterId": character_id,
2464                "membershipType": int(membership_type),
2465            },
2466        )
2467        assert isinstance(response, int)
2468
2469    async def clear_loadout(
2470        self,
2471        access_token: str,
2472        /,
2473        loadout_index: int,
2474        character_id: int,
2475        membership_type: enums.MembershipType | int,
2476    ) -> None:
2477        response = await self._request(
2478            _POST,
2479            "Destiny2/Actions/Loadouts/ClearLoadout/",
2480            json={
2481                "loadoutIndex": loadout_index,
2482                "characterId": character_id,
2483                "membership_type": int(membership_type),
2484            },
2485            auth=access_token,
2486        )
2487        assert isinstance(response, int)
2488
2489    async def force_drops_repair(self, access_token: str, /) -> bool:
2490        response = await self._request(
2491            _POST, "Tokens/Partner/ForceDropsRepair/", auth=access_token
2492        )
2493        assert isinstance(response, bool)
2494        return response
2495
2496    async def claim_partner_offer(
2497        self,
2498        access_token: str,
2499        /,
2500        *,
2501        offer_id: str,
2502        bungie_membership_id: int,
2503        transaction_id: str,
2504    ) -> bool:
2505        response = await self._request(
2506            _POST,
2507            "Tokens/Partner/ClaimOffer/",
2508            json={
2509                "PartnerOfferId": offer_id,
2510                "BungieNetMembershipId": bungie_membership_id,
2511                "TransactionId": transaction_id,
2512            },
2513            auth=access_token,
2514        )
2515        assert isinstance(response, bool)
2516        return response
2517
2518    async def fetch_bungie_rewards_for_user(
2519        self, access_token: str, /, membership_id: int
2520    ) -> typedefs.JSONObject:
2521        response = await self._request(
2522            _GET,
2523            f"Tokens/Rewards/GetRewardsForUser/{membership_id}/",
2524            auth=access_token,
2525        )
2526        assert isinstance(response, dict)
2527        return response
2528
2529    async def fetch_bungie_rewards_for_platform(
2530        self,
2531        access_token: str,
2532        /,
2533        membership_id: int,
2534        membership_type: enums.MembershipType | int,
2535    ) -> typedefs.JSONObject:
2536        response = await self._request(
2537            _GET,
2538            f"Tokens/Rewards/GetRewardsForPlatformUser/{membership_id}/{int(membership_type)}",
2539            auth=access_token,
2540        )
2541        assert isinstance(response, dict)
2542        return response
2543
2544    async def fetch_bungie_rewards(self) -> typedefs.JSONObject:
2545        response = await self._request(_GET, "Tokens/Rewards/BungieRewards/")
2546        assert isinstance(response, dict)
2547        return response
2548
2549    async def fetch_fireteam_listing(self, listing_id: int) -> typedefs.JSONObject:
2550        response = await self._request(_GET, f"FireteamFinder/Listing/{listing_id}/")
2551        assert isinstance(response, dict)
2552        return response