otf-api 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

otf_api/api/client.py

@@ -0,0 +1,203 @@
+import atexit
+import re
+from json import JSONDecodeError
+from logging import getLogger
+from typing import Any
+
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+from yarl import URL
+
+from otf_api import exceptions as exc
+from otf_api.api.utils import get_json_from_response, is_error_response
+from otf_api.auth import OtfUser
+from otf_api.cache import get_cache
+
+API_BASE_URL = "api.orangetheory.co"
+API_IO_BASE_URL = "api.orangetheory.io"
+API_TELEMETRY_BASE_URL = "api.yuzu.orangetheory.com"
+HEADERS = {
+    "content-type": "application/json",
+    "accept": "application/json",
+    "user-agent": "okhttp/4.12.0",
+}
+CACHE = get_cache()
+LOGGER = getLogger(__name__)
+
+
+class OtfClient:
+    """Client for interacting with the OTF API - generally to be used by the Otf class.
+
+    This class provides methods to perform various API requests, including booking classes,
+    retrieving member details, and managing bookings. It handles authentication and session management
+    using the provided OtfUser instance or a default unauthenticated user.
+
+    It also includes retry logic for handling transient errors and caching for performance optimization.
+    """
+
+    def __init__(self, user: OtfUser | None = None):
+        """Initialize the OTF API client.
+
+        Args:
+            user (OtfUser): The user to authenticate as.
+        """
+        self.user = user or OtfUser()
+        self.member_uuid = self.user.member_uuid
+
+        self.session = httpx.Client(
+            headers=HEADERS, auth=self.user.httpx_auth, timeout=httpx.Timeout(20.0, connect=60.0)
+        )
+        atexit.register(self.session.close)
+
+    def _build_request(
+        self,
+        method: str,
+        full_url: str,
+        params: dict[str, Any] | None,
+        headers: dict[str, str] | None,
+        **kwargs,
+    ) -> httpx.Request:
+        params = {k: v for k, v in (params or {}).items() if v is not None}
+        headers = headers or {}
+        return self.session.build_request(method, full_url, headers=headers, params=params, **kwargs)
+
+    @retry(
+        retry=retry_if_exception_type((exc.RetryableOtfRequestError, httpx.HTTPStatusError)),
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=4, max=10),
+        reraise=True,
+    )
+    def do(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        **kwargs,
+    ) -> Any:  # noqa: ANN401
+        """Perform an API request.
+
+        Args:
+            method (str): The HTTP method to use (e.g., 'GET', 'POST').
+            base_url (str): The base URL for the API.
+            path (str): The specific endpoint to request.
+            params (dict[str, Any] | None): Query parameters to include in the request.
+            headers (dict[str, str] | None): Additional headers to include in the request.
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            Any: The response data from the API request.
+
+        Raises:
+            OtfRequestError: If the request fails or the response is invalid.
+            HTTPStatusError: If the response status code indicates an error.
+        """
+        full_url = str(URL.build(scheme="https", host=base_url, path=path))
+        request = self._build_request(method, full_url, params, headers, **kwargs)
+        LOGGER.debug(f"Making {method!r} request to '{full_url}', params: {params}, headers: {headers}")
+
+        try:
+            response = self.session.send(request)
+            response.raise_for_status()
+        except Exception as e:
+            self._handle_transport_error(e, request)
+            raise
+
+        return self._handle_response(method, response, request)
+
+    def default_request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> Any:  # noqa: ANN401
+        """Perform an API request to the default API."""
+        return self.do(method, API_BASE_URL, path, params, headers=headers, **kwargs)
+
+    def _map_http_error(
+        self, data: dict, error: httpx.HTTPStatusError, response: httpx.Response, request: httpx.Request
+    ) -> None:
+        code = data.get("code")
+        path = request.url.path
+        error_code = data.get("data", {}).get("errorCode")
+        error_msg = data.get("message") or data.get("data", {}).get("message", "") or ""
+
+        if response.status_code == 404:
+            raise exc.ResourceNotFoundError(f"Resource not found: {path}")
+
+        # Match based on error code and path
+        if re.match(r"^/v1/bookings/me", path):
+            if code == "BOOKING_CANCELED":
+                raise exc.BookingAlreadyCancelledError(error_msg or "Booking was already cancelled")
+            if code == "BOOKING_ALREADY_BOOKED":
+                raise exc.AlreadyBookedError("This class is already booked")
+
+        if re.match(r"^/member/members/.*?/bookings", path):
+            if code == "NOT_AUTHORIZED" and error_msg.startswith("This class booking has been cancelled"):
+                raise exc.BookingNotFoundError("Booking was already cancelled")
+            if error_code == "603":
+                raise exc.AlreadyBookedError("Class is already booked")
+            if error_code == "602":
+                raise exc.OutsideSchedulingWindowError("Class is outside scheduling window")
+
+        msg = f"HTTP error {error.response.status_code} for {request.method} {request.url}"
+        LOGGER.error(msg)
+        error_cls = exc.RetryableOtfRequestError if response.status_code >= 500 else exc.OtfRequestError
+        raise error_cls(message=msg, original_exception=error, request=request, response=response)
+
+    def _handle_transport_error(self, error: Exception, request: httpx.Request) -> None:
+        """Handle transport errors during API requests.
+
+        Generally we let these bubble up to the caller so they get retried, but there are a few
+        cases where we want to log the error and raise a specific exception.
+
+        Args:
+            error (Exception): The exception raised during the request.
+            request (httpx.Request): The request that caused the error.
+        """
+        method = request.method
+        url = request.url
+
+        if not isinstance(error, httpx.HTTPStatusError):
+            LOGGER.exception(f"Unexpected error during {method!r} {url!r}: {type(error).__name__} - {error}")
+            return
+
+        json_data = get_json_from_response(error.response)
+        self._map_http_error(json_data, error, error.response, request)
+
+        return
+
+    def _map_logical_error(self, data: dict, response: httpx.Response, request: httpx.Request) -> None:
+        # not actually sure this is necessary, so far all of them have been HttpStatusError
+        data_status: int | None = data.get("Status") or data.get("status") or None
+
+        if isinstance(data, dict) and isinstance(data_status, int) and not 200 <= data_status <= 299:
+            LOGGER.error(f"API returned error: {data}")
+            raise exc.OtfRequestError("Bad API response", None, response=response, request=request)
+
+        raise exc.OtfRequestError(
+            f"Logical error in API response: {data}", original_exception=None, response=response, request=request
+        )
+
+    def _handle_response(self, method: str, response: httpx.Response, request: httpx.Request) -> Any:  # noqa: ANN401
+        if not response.text:
+            if method == "GET":
+                raise exc.OtfRequestError("Empty response", None, response=response, request=request)
+
+            LOGGER.debug(f"No content returned from {method} {response.url}")
+            return None
+
+        try:
+            json_data = response.json()
+        except JSONDecodeError as e:
+            LOGGER.error(f"Invalid JSON: {e}")
+            LOGGER.error(f"Response content: {response.text}")
+            raise
+
+        if is_error_response(json_data):
+            self._map_logical_error(json_data, response, request)
+
+        return json_data

otf_api/api/members/__init__.py

@@ -0,0 +1,3 @@
+from .member_api import MemberApi
+
+__all__ = ["MemberApi"]

otf_api/api/members/member_api.py

@@ -0,0 +1,187 @@
+import typing
+from logging import getLogger
+from typing import Any
+
+from otf_api import models
+from otf_api.api.client import OtfClient
+
+from .member_client import MemberClient
+
+if typing.TYPE_CHECKING:
+    from otf_api import Otf
+
+LOGGER = getLogger(__name__)
+
+
+class MemberApi:
+    def __init__(self, otf: "Otf", otf_client: OtfClient):
+        """Initialize the Member API client.
+
+        Args:
+            otf (Otf): The OTF API client.
+            otf_client (OtfClient): The OTF client to use for requests.
+        """
+        self.otf = otf
+        self.client = MemberClient(otf_client)
+
+    def get_sms_notification_settings(self) -> models.SmsNotificationSettings:
+        """Get the member's SMS notification settings.
+
+        Returns:
+            SmsNotificationSettings: The member's SMS notification settings.
+        """
+        res = self.client.get_sms_notification_settings(self.otf.member.phone_number)  # type: ignore
+
+        return models.SmsNotificationSettings(**res)
+
+    def update_sms_notification_settings(
+        self, promotional_enabled: bool | None = None, transactional_enabled: bool | None = None
+    ) -> models.SmsNotificationSettings:
+        """Update the member's SMS notification settings. Arguments not provided will be left unchanged.
+
+        Args:
+            promotional_enabled (bool | None): Whether to enable promotional SMS notifications.
+            transactional_enabled (bool | None): Whether to enable transactional SMS notifications.
+
+        Returns:
+            SmsNotificationSettings: The updated SMS notification settings.
+        """
+        current_settings = self.get_sms_notification_settings()
+
+        promotional_enabled = (
+            promotional_enabled if promotional_enabled is not None else current_settings.is_promotional_sms_opt_in
+        )
+        transactional_enabled = (
+            transactional_enabled if transactional_enabled is not None else current_settings.is_transactional_sms_opt_in
+        )
+
+        self.client.post_sms_notification_settings(
+            self.otf.member.phone_number,  # type: ignore
+            promotional_enabled,  # type: ignore
+            transactional_enabled,  # type: ignore
+        )
+
+        # the response returns nothing useful, so we just query the settings again
+        new_settings = self.get_sms_notification_settings()
+        return new_settings
+
+    def get_email_notification_settings(self) -> models.EmailNotificationSettings:
+        """Get the member's email notification settings.
+
+        Returns:
+            EmailNotificationSettings: The member's email notification settings.
+        """
+        res = self.client.get_email_notification_settings(self.otf.member.email)  # type: ignore
+
+        return models.EmailNotificationSettings(**res)
+
+    def update_email_notification_settings(
+        self, promotional_enabled: bool | None = None, transactional_enabled: bool | None = None
+    ) -> models.EmailNotificationSettings:
+        """Update the member's email notification settings. Arguments not provided will be left unchanged.
+
+        Args:
+            promotional_enabled (bool | None): Whether to enable promotional email notifications.
+            transactional_enabled (bool | None): Whether to enable transactional email notifications.
+
+        Returns:
+            EmailNotificationSettings: The updated email notification settings.
+        """
+        current_settings = self.get_email_notification_settings()
+
+        promotional_enabled = (
+            promotional_enabled if promotional_enabled is not None else current_settings.is_promotional_email_opt_in
+        )
+        transactional_enabled = (
+            transactional_enabled
+            if transactional_enabled is not None
+            else current_settings.is_transactional_email_opt_in
+        )
+
+        self.client.post_email_notification_settings(
+            self.otf.member.email,  # type: ignore
+            promotional_enabled,  # type: ignore
+            transactional_enabled,  # type: ignore
+        )
+
+        # the response returns nothing useful, so we just query the settings again
+        new_settings = self.get_email_notification_settings()
+        return new_settings
+
+    def update_member_name(self, first_name: str | None = None, last_name: str | None = None) -> models.MemberDetail:
+        """Update the member's name. Will return the original member details if no names are provided.
+
+        Args:
+            first_name (str | None): The first name to update to. Default is None.
+            last_name (str | None): The last name to update to. Default is None.
+
+        Returns:
+            MemberDetail: The updated member details or the original member details if no changes were made.
+        """
+        if not first_name and not last_name:
+            LOGGER.warning("No names provided, nothing to update.")
+            return self.otf.member
+
+        first_name = first_name or self.otf.member.first_name
+        last_name = last_name or self.otf.member.last_name
+
+        if first_name == self.otf.member.first_name and last_name == self.otf.member.last_name:
+            LOGGER.warning("No changes to names, nothing to update.")
+            return self.otf.member
+
+        assert first_name is not None, "First name is required"
+        assert last_name is not None, "Last name is required"
+
+        res = self.client.put_member_name(first_name, last_name)
+
+        return models.MemberDetail.create(**res, api=self)
+
+    def get_member_detail(self) -> models.MemberDetail:
+        """Get the member details.
+
+        Returns:
+            MemberDetail: The member details.
+        """
+        data = self.client.get_member_detail()
+
+        # use standard StudioDetail model instead of the one returned by this endpoint
+        home_studio_uuid = data["homeStudio"]["studioUUId"]
+        data["home_studio"] = self.otf.studios.get_studio_detail(home_studio_uuid)
+
+        return models.MemberDetail.create(**data, api=self)
+
+    def get_member_membership(self) -> models.MemberMembership:
+        """Get the member's membership details.
+
+        Returns:
+            MemberMembership: The member's membership details.
+        """
+        data = self.client.get_member_membership()
+        return models.MemberMembership(**data)
+
+    def get_member_purchases(self) -> list[models.MemberPurchase]:
+        """Get the member's purchases, including monthly subscriptions and class packs.
+
+        Returns:
+            list[MemberPurchase]: The member's purchases.
+        """
+        purchases = self.client.get_member_purchases()
+
+        for p in purchases:
+            p["studio"] = self.otf.studios.get_studio_detail(p["studio"]["studioUUId"])
+
+        return [models.MemberPurchase(**purchase) for purchase in purchases]
+
+    # the below do not return any data for me, so I can't test them
+
+    def _get_member_services(self, active_only: bool = True) -> Any:  # noqa: ANN401
+        """Get the member's services.
+
+        Args:
+            active_only (bool): Whether to only include active services. Default is True.
+
+        Returns:
+            Any: The member's services.
+        """
+        data = self.client.get_member_services(active_only)
+        return data

otf_api/api/members/member_client.py

@@ -0,0 +1,112 @@
+from typing import Any
+
+from otf_api.api.client import CACHE, OtfClient
+
+
+class MemberClient:
+    """Client for retrieving and managing member data in the OTF API.
+
+    This class provides methods to access member details, membership information, notification settings,
+    and member services. It also allows updating member information such as name and notification preferences.
+    """
+
+    def __init__(self, client: OtfClient):
+        self.client = client
+        self.member_uuid = client.member_uuid
+
+    @CACHE.memoize(expire=600, tag="member_detail", ignore=(0,))
+    def get_member_detail(self) -> dict:
+        """Retrieve raw member details."""
+        return self.client.default_request(
+            "GET", f"/member/members/{self.member_uuid}", params={"include": "memberAddresses,memberClassSummary"}
+        )["data"]
+
+    def get_member_membership(self) -> dict:
+        """Retrieve raw member membership details."""
+        return self.client.default_request("GET", f"/member/members/{self.member_uuid}/memberships")["data"]
+
+    def get_sms_notification_settings(self, phone_number: str) -> dict:
+        """Retrieve raw SMS notification settings."""
+        return self.client.default_request("GET", path="/sms/v1/preferences", params={"phoneNumber": phone_number})[
+            "data"
+        ]
+
+    def get_email_notification_settings(self, email: str) -> dict:
+        """Retrieve raw email notification settings."""
+        return self.client.default_request("GET", path="/otfmailing/v2/preferences", params={"email": email})["data"]
+
+    def get_member_services(self, active_only: bool) -> dict:
+        """Retrieve raw member services data."""
+        return self.client.default_request(
+            "GET", f"/member/members/{self.member_uuid}/services", params={"activeOnly": str(active_only).lower()}
+        )
+
+    def get_member_purchases(self) -> dict:
+        """Retrieve raw member purchases data."""
+        return self.client.default_request("GET", f"/member/members/{self.member_uuid}/purchases")["data"]
+
+    def post_sms_notification_settings(
+        self, phone_number: str, promotional_enabled: bool, transactional_enabled: bool
+    ) -> dict:
+        """Retrieve raw response from updating SMS notification settings.
+
+        Warning:
+            This endpoint seems to accept almost anything, converting values to truthy/falsey and
+            updating the settings accordingly. The one error I've gotten is with -1
+
+            ```
+            ERROR - Response:
+            {
+            "code": "ER_WARN_DATA_OUT_OF_RANGE",
+            "message": "An unexpected server error occurred, please try again.",
+            "details": [
+                    {
+                "message": "ER_WARN_DATA_OUT_OF_RANGE: Out of range value for column 'IsPromotionalSMSOptIn' at row 1",
+                "additionalInfo": ""
+                    }
+                ]
+            }
+            ```
+        """
+        return self.client.default_request(
+            "POST",
+            "/sms/v1/preferences",
+            json={
+                "promosms": promotional_enabled,
+                "source": "OTF",
+                "transactionalsms": transactional_enabled,
+                "phoneNumber": phone_number,
+            },
+        )
+
+    def post_email_notification_settings(
+        self, email: str, promotional_enabled: bool, transactional_enabled: bool
+    ) -> dict:
+        """Retrieve raw response from updating email notification settings."""
+        return self.client.default_request(
+            "POST",
+            "/otfmailing/v2/preferences",
+            json={
+                "promotionalEmail": promotional_enabled,
+                "source": "OTF",
+                "transactionalEmail": transactional_enabled,
+                "email": email,
+            },
+        )
+
+    def put_member_name(self, first_name: str, last_name: str) -> dict:
+        """Retrieve raw response from updating member name."""
+        CACHE.evict(tag="member_detail", retry=True)
+        return self.client.default_request(
+            "PUT",
+            f"/member/members/{self.member_uuid}",
+            json={"firstName": first_name, "lastName": last_name},
+        )["data"]
+
+    def get_app_config(self) -> dict[str, Any]:
+        """Retrieve raw app configuration data.
+
+        Returns:
+            dict[str, Any]: A dictionary containing app configuration data.
+        """
+        return self.client.default_request("GET", "/member/app-configurations", headers={"SIGV4AUTH_REQUIRED": "true"})

otf_api/api/studios/__init__.py

@@ -0,0 +1,3 @@
+from .studio_api import StudioApi
+
+__all__ = ["StudioApi"]

otf_api/api/studios/studio_api.py

@@ -0,0 +1,173 @@
+import typing
+from logging import getLogger
+
+from otf_api import exceptions as exc
+from otf_api import models
+from otf_api.api import utils
+from otf_api.api.client import OtfClient
+
+from .studio_client import StudioClient
+
+if typing.TYPE_CHECKING:
+    from otf_api import Otf
+
+LOGGER = getLogger(__name__)
+
+
+class StudioApi:
+    def __init__(self, otf: "Otf", otf_client: OtfClient):
+        """Initialize the Studio API client.
+
+        Args:
+            otf (Otf): The OTF API client.
+            otf_client (OtfClient): The OTF client to use for requests.
+        """
+        self.otf = otf
+        self.client = StudioClient(otf_client)
+
+    def get_favorite_studios(self) -> list[models.StudioDetail]:
+        """Get the member's favorite studios.
+
+        Returns:
+            list[StudioDetail]: The member's favorite studios.
+        """
+        data = self.client.get_favorite_studios()
+        studio_uuids = [studio["studioUUId"] for studio in data]
+        return [self.get_studio_detail(studio_uuid) for studio_uuid in studio_uuids]
+
+    def add_favorite_studio(self, studio_uuids: list[str] | str) -> list[models.StudioDetail]:
+        """Add a studio to the member's favorite studios.
+
+        Args:
+            studio_uuids (list[str] | str): The studio UUID or list of studio UUIDs to add to the member's favorite\
+            studios. If a string is provided, it will be converted to a list.
+
+        Returns:
+            list[StudioDetail]: The new favorite studios.
+        """
+        studio_uuids = utils.ensure_list(studio_uuids)
+
+        if not studio_uuids:
+            raise ValueError("studio_uuids is required")
+
+        resp = self.client.post_favorite_studio(studio_uuids)
+        if not resp:
+            return []
+
+        new_faves = resp.get("studios", [])
+
+        return [models.StudioDetail.create(**studio, api=self) for studio in new_faves]
+
+    def remove_favorite_studio(self, studio_uuids: list[str] | str) -> None:
+        """Remove a studio from the member's favorite studios.
+
+        Args:
+            studio_uuids (list[str] | str): The studio UUID or list of studio UUIDs to remove from the member's\
+            favorite studios. If a string is provided, it will be converted to a list.
+
+        Returns:
+            None
+        """
+        studio_uuids = utils.ensure_list(studio_uuids)
+
+        if not studio_uuids:
+            raise ValueError("studio_uuids is required")
+
+        # keeping the convention of regular/raw methods even though this method doesn't return anything
+        # in case that changes in the future
+        self.client.delete_favorite_studio(studio_uuids)
+
+    def get_studio_services(self, studio_uuid: str | None = None) -> list[models.StudioService]:
+        """Get the services available at a specific studio.
+
+        If no studio UUID is provided, the member's home studio will be used.
+
+        Args:
+            studio_uuid (str, optional): The studio UUID to get services for.
+
+        Returns:
+            list[StudioService]: The services available at the studio.
+        """
+        studio_uuid = studio_uuid or self.otf.home_studio_uuid
+        data = self.client.get_studio_services(studio_uuid)
+
+        for d in data:
+            d["studio"] = self.get_studio_detail(studio_uuid)
+
+        return [models.StudioService(**d) for d in data]
+
+    def get_studio_detail(self, studio_uuid: str | None = None) -> models.StudioDetail:
+        """Get detailed information about a specific studio.
+
+        If no studio UUID is provided, it will default to the user's home studio.
+
+        If the studio is not found, it will return a StudioDetail object with default values.
+
+        Args:
+            studio_uuid (str, optional): The studio UUID to get detailed information about.
+
+        Returns:
+            StudioDetail: Detailed information about the studio.
+        """
+        studio_uuid = studio_uuid or self.otf.home_studio_uuid
+
+        try:
+            res = self.client.get_studio_detail(studio_uuid)
+        except exc.ResourceNotFoundError:
+            return models.StudioDetail.create_empty_model(studio_uuid)
+
+        return models.StudioDetail.create(**res, api=self)
+
+    def get_studios_by_geo(
+        self, latitude: float | None = None, longitude: float | None = None
+    ) -> list[models.StudioDetail]:
+        """Alias for search_studios_by_geo."""
+        return self.search_studios_by_geo(latitude, longitude)
+
+    def search_studios_by_geo(
+        self, latitude: float | None = None, longitude: float | None = None, distance: int = 50
+    ) -> list[models.StudioDetail]:
+        """Search for studios by geographic location.
+
+        Args:
+            latitude (float, optional): Latitude of the location to search around, if None uses home studio latitude.
+            longitude (float, optional): Longitude of the location to search around, if None uses home studio longitude.
+            distance (int, optional): The distance in miles to search around the location. Default is 50.
+
+        Returns:
+            list[StudioDetail]: List of studios that match the search criteria.
+        """
+        latitude = latitude or self.otf.home_studio.location.latitude
+        longitude = longitude or self.otf.home_studio.location.longitude
+
+        results = self.client.get_studios_by_geo(latitude, longitude, distance)
+        return [models.StudioDetail.create(**studio, api=self) for studio in results]
+
+    def _get_all_studios(self) -> list[models.StudioDetail]:
+        """Gets all studios. Marked as private to avoid random users calling it.
+
+        Useful for testing and validating models.
+
+        Returns:
+            list[StudioDetail]: List of studios that match the search criteria.
+        """
+        # long/lat being None will cause the endpoint to return all studios
+        results = self.client.get_studios_by_geo(None, None)
+        return [models.StudioDetail.create(**studio, api=self) for studio in results]
+
+    def _get_studio_detail_threaded(self, studio_uuids: list[str]) -> dict[str, models.StudioDetail]:
+        """Get detailed information about multiple studios in a threaded manner.
+
+        This is used to improve performance when fetching details for multiple studios at once.
+        This method is on the Otf class because StudioDetail is a model that requires the API instance.
+
+        Args:
+            studio_uuids (list[str]): List of studio UUIDs to get details for.
+
+        Returns:
+            dict[str, StudioDetail]: A dictionary mapping studio UUIDs to their detailed information.
+        """
+        studio_dicts = self.client.get_studio_detail_threaded(studio_uuids)
+        return {
+            studio_uuid: models.StudioDetail.create(**studio, api=self) for studio_uuid, studio in studio_dicts.items()
+        }