otf-api 0.9.0__tar.gz → 0.9.2__tar.gz

{otf_api-0.9.0 → otf_api-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: otf-api
-Version: 0.9.0
+Version: 0.9.2
 Summary: Python OrangeTheory Fitness API Client
 License: MIT
 Author: Jessica Smith
@@ -44,11 +44,20 @@ pip install otf-api
 
 ## Overview
 
-To use the API, you need to create an instance of the `Otf` class, providing your email address and password. This will authenticate you with the API and allow you to make requests. When the `Otf` object is created it automatically grabs your member details and home studio, to simplify the process of making requests.
+To use the API, you need to create an instance of the `Otf` class. This will authenticate you with the API and allow you to make requests. When the `Otf` object is created it automatically grabs your member details and home studio, to simplify the process of making requests.
 
+You can either pass an `OtfUser` object to the `OtfClass` or you can pass nothing and allow it to prompt you for your username and password.
 
-See the [examples](./examples) for more information on how to use the API.
+You can also export environment variables `OTF_EMAIL` and `OTF_PASSWORD` to get these from the environment.
 
-Disclaimer:
-This project is in no way affiliated with OrangeTheory Fitness.
+```python
+from otf_api import Otf, OtfUser
+
+otf = Otf()
+
+# OR
+
+otf = Otf(user=OtfUser(<email_address>,<password>))
+
+```
 

otf_api-0.9.2/README.md

@@ -0,0 +1,30 @@
+Simple API client for interacting with the OrangeTheory Fitness APIs.
+
+Review the [documentation](https://otf-api.readthedocs.io/en/stable/).
+
+
+This library allows access to the OrangeTheory API to retrieve workouts and performance data, class schedules, studio information, and bookings.
+
+## Installation
+```bash
+pip install otf-api
+```
+
+## Overview
+
+To use the API, you need to create an instance of the `Otf` class. This will authenticate you with the API and allow you to make requests. When the `Otf` object is created it automatically grabs your member details and home studio, to simplify the process of making requests.
+
+You can either pass an `OtfUser` object to the `OtfClass` or you can pass nothing and allow it to prompt you for your username and password.
+
+You can also export environment variables `OTF_EMAIL` and `OTF_PASSWORD` to get these from the environment.
+
+```python
+from otf_api import Otf, OtfUser
+
+otf = Otf()
+
+# OR
+
+otf = Otf(user=OtfUser(<email_address>,<password>))
+
+```

{otf_api-0.9.0 → otf_api-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "otf-api"
-version = "0.9.0"
+version = "0.9.2"
 description = "Python OrangeTheory Fitness API Client"
 authors = ["Jessica Smith <j.smith.git1@gmail.com>"]
 license = "MIT"

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/__init__.py

@@ -4,7 +4,7 @@ from otf_api.api import Otf
 from otf_api import models
 from otf_api.auth import OtfUser
 
-__version__ = "0.9.0"
+__version__ = "0.9.2"
 
 
 __all__ = ["Otf", "OtfUser", "models"]

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/api.py

@@ -87,9 +87,7 @@ class Otf:
             LOGGER.exception(f"Response: {response.text}")
             raise
         except httpx.HTTPStatusError as e:
-            LOGGER.exception(f"Error making request: {e}")
-            LOGGER.exception(f"Response: {response.text}")
-            raise exc.OtfRequestError("Error making request", response=response, request=request)
+            raise exc.OtfRequestError("Error making request", e, response=response, request=request)
         except Exception as e:
             LOGGER.exception(f"Error making request: {e}")
             raise
@@ -110,7 +108,7 @@ class Otf:
             and not (resp["Status"] >= 200 and resp["Status"] <= 299)
         ):
             LOGGER.error(f"Error making request: {resp}")
-            raise exc.OtfRequestError("Error making request", response=response, request=request)
+            raise exc.OtfRequestError("Error making request", None, response=response, request=request)
 
         return resp
 
@@ -966,6 +964,7 @@ class Otf:
 
         path = f"/v1/performance-summaries/{performance_summary_id}"
         res = self._performance_summary_request("GET", path)
+
         if res is None:
             raise exc.ResourceNotFoundError(f"Performance summary {performance_summary_id} not found")
 
@@ -1007,14 +1006,58 @@ class Otf:
         res = self._telemetry_request("GET", path, params=params)
         return models.Telemetry(**res)
 
-    def get_sms_notification_settings(self):
+    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._default_request("GET", url="/sms/v1/preferences", params={"phoneNumber": self.member.phone_number})
 
-        return res["data"]
+        return models.SmsNotificationSettings(**res["data"])
+
+    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.
 
-    def update_sms_notification_settings(self, promotional_enabled: bool, transactional_enabled: bool):
+        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": ""
+                    }
+                ]
+            }
+            ```
+        """
         url = "/sms/v1/preferences"
 
+        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
+        )
+
         body = {
             "promosms": promotional_enabled,
             "source": "OTF",
@@ -1022,11 +1065,45 @@ class Otf:
             "phoneNumber": self.member.phone_number,
         }
 
-        res = self._default_request("POST", url, json=body)
+        self._default_request("POST", url, json=body)
+
+        # 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.
 
-        return res["data"]
+        Returns:
+            EmailNotificationSettings: The member's email notification settings.
+        """
+        res = self._default_request("GET", url="/otfmailing/v2/preferences", params={"email": self.member.email})
+
+        return models.EmailNotificationSettings(**res["data"])
+
+    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
+        )
 
-    def update_email_notification_settings(self, promotional_enabled: bool, transactional_enabled: bool):
         body = {
             "promotionalEmail": promotional_enabled,
             "source": "OTF",
@@ -1034,9 +1111,11 @@ class Otf:
             "email": self.member.email,
         }
 
-        res = self._default_request("POST", "/otfmailing/v2/preferences", json=body)
+        self._default_request("POST", "/otfmailing/v2/preferences", json=body)
 
-        return res["data"]
+        # 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.
@@ -1067,6 +1146,137 @@ class Otf:
 
         return models.MemberDetail(**res["data"])
 
+    def _rate_class(
+        self,
+        class_uuid: str,
+        class_history_uuid: str,
+        class_rating: Literal[0, 1, 2, 3],
+        coach_rating: Literal[0, 1, 2, 3],
+    ) -> models.PerformanceSummaryEntry:
+        """Rate a class and coach. A simpler method is provided in `rate_class_from_performance_summary`.
+
+
+        The class rating must be between 0 and 4.
+        0 is the same as dismissing the prompt to rate the class/coach in the app.
+        1 through 3 is a range from bad to good.
+
+        Args:
+            class_uuid (str): The class UUID.
+            class_history_uuid (str): The performance summary ID.
+            class_rating (int): The class rating. Must be 0, 1, 2, or 3.
+            coach_rating (int): The coach rating. Must be 0, 1, 2, or 3.
+
+        Returns:
+            PerformanceSummaryEntry: The updated performance summary entry.
+        """
+
+        # com/orangetheoryfitness/fragment/rating/RateStatus.java
+
+        # we convert these to the new values that the app uses
+        # mainly because we don't want to cause any issues with the API and/or with OTF corporate
+        # wondering where the old values are coming from
+
+        COACH_RATING_MAP = {0: 0, 1: 16, 2: 17, 3: 18}
+        CLASS_RATING_MAP = {0: 0, 1: 19, 2: 20, 3: 21}
+
+        if class_rating not in CLASS_RATING_MAP:
+            raise ValueError(f"Invalid class rating {class_rating}")
+
+        if coach_rating not in COACH_RATING_MAP:
+            raise ValueError(f"Invalid coach rating {coach_rating}")
+
+        body_class_rating = CLASS_RATING_MAP[class_rating]
+        body_coach_rating = COACH_RATING_MAP[coach_rating]
+
+        body = {
+            "classUUId": class_uuid,
+            "otBeatClassHistoryUUId": class_history_uuid,
+            "classRating": body_class_rating,
+            "coachRating": body_coach_rating,
+        }
+
+        try:
+            self._default_request("POST", "/mobile/v1/members/classes/ratings", json=body)
+        except exc.OtfRequestError as e:
+            if e.response.status_code == 403:
+                raise exc.AlreadyRatedError(f"Performance summary {class_history_uuid} is already rated.") from None
+            raise
+
+        return self._get_performance_summary_entry_from_id(class_history_uuid)
+
+    def _get_performance_summary_entry_from_id(self, class_history_uuid: str) -> models.PerformanceSummaryEntry:
+        """Get a performance summary entry from the ID.
+
+        This is a helper function to compensate for the fact that a PerformanceSummaryDetail object does not contain
+        the class UUID, which is required to rate the class. It will also be used to return an updated performance
+        summary entry after rating a class.
+
+        Args:
+            class_history_uuid (str): The performance summary ID.
+
+        Returns:
+            PerformanceSummaryEntry: The performance summary entry.
+
+        Raises:
+            ResourceNotFoundError: If the performance summary is not found.
+        """
+
+        # try going in as small of increments as possible, assuming that the rating request
+        # will be for a recent class
+        for limit in [5, 20, 60, 100]:
+            summaries = self.get_performance_summaries(limit)
+            summary = next((s for s in summaries if s.class_history_uuid == class_history_uuid), None)
+
+            if summary:
+                return summary
+
+        raise exc.ResourceNotFoundError(f"Performance summary {class_history_uuid} not found.")
+
+    def rate_class_from_performance_summary(
+        self,
+        perf_summary: models.PerformanceSummaryEntry | models.PerformanceSummaryDetail,
+        class_rating: Literal[0, 1, 2, 3],
+        coach_rating: Literal[0, 1, 2, 3],
+    ) -> models.PerformanceSummaryEntry:
+        """Rate a class and coach. The class rating must be 0, 1, 2, or 3. 0 is the same as dismissing the prompt to
+            rate the class/coach. 1 - 3 is a range from bad to good.
+
+        Args:
+            perf_summary (PerformanceSummaryEntry): The performance summary entry to rate.
+            class_rating (int): The class rating. Must be 0, 1, 2, or 3.
+            coach_rating (int): The coach rating. Must be 0, 1, 2, or 3.
+
+        Returns:
+            PerformanceSummaryEntry: The updated performance summary entry.
+
+        Raises:
+            ValueError: If `perf_summary` is not a PerformanceSummaryEntry.
+            AlreadyRatedError: If the performance summary is already rated.
+            ClassNotRatableError: If the performance summary is not rateable.
+            ValueError: If the performance summary does not have an associated class.
+        """
+
+        if isinstance(perf_summary, models.PerformanceSummaryDetail):
+            perf_summary = self._get_performance_summary_entry_from_id(perf_summary.class_history_uuid)
+
+        if not isinstance(perf_summary, models.PerformanceSummaryEntry):
+            raise ValueError(f"`perf_summary` must be a PerformanceSummaryEntry, got {type(perf_summary)}")
+
+        if perf_summary.is_rated:
+            raise exc.AlreadyRatedError(f"Performance summary {perf_summary.class_history_uuid} is already rated.")
+
+        if not perf_summary.ratable:
+            raise exc.ClassNotRatableError(f"Performance summary {perf_summary.class_history_uuid} is not rateable.")
+
+        if not perf_summary.otf_class or not perf_summary.otf_class.class_uuid:
+            raise ValueError(
+                f"Performance summary {perf_summary.class_history_uuid} does not have an associated class."
+            )
+
+        return self._rate_class(
+            perf_summary.otf_class.class_uuid, perf_summary.class_history_uuid, class_rating, coach_rating
+        )
+
     # 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:

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/exceptions.py

@@ -8,11 +8,13 @@ class OtfException(Exception):
 class OtfRequestError(OtfException):
     """Raised when an error occurs while making a request to the OTF API."""
 
+    original_exception: Exception
     response: Response
     request: Request
 
-    def __init__(self, message: str, response: Response, request: Request):
+    def __init__(self, message: str, original_exception: Exception | None, response: Response, request: Request):
         super().__init__(message)
+        self.original_exception = original_exception
         self.response = response
         self.request = request
 
@@ -49,3 +51,11 @@ class BookingNotFoundError(OtfException):
 
 class ResourceNotFoundError(OtfException):
     """Raised when a resource is not found."""
+
+
+class AlreadyRatedError(OtfException):
+    """Raised when attempting to rate a class that is already rated."""
+
+
+class ClassNotRatableError(OtfException):
+    """Raised when attempting to rate a class that is not ratable."""

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/models/__init__.py

@@ -8,6 +8,7 @@ from .lifetime_stats import StatsResponse, TimeStats
 from .member_detail import MemberDetail
 from .member_membership import MemberMembership
 from .member_purchases import MemberPurchase
+from .notifications import EmailNotificationSettings, SmsNotificationSettings
 from .out_of_studio_workout_history import OutOfStudioWorkoutHistory
 from .performance_summary_detail import PerformanceSummaryDetail
 from .performance_summary_list import PerformanceSummaryEntry
@@ -24,6 +25,7 @@ __all__ = [
     "ChallengeTracker",
     "ClassType",
     "DoW",
+    "EmailNotificationSettings",
     "EquipmentType",
     "FitnessBenchmark",
     "LatestAgreement",
@@ -34,6 +36,7 @@ __all__ = [
     "OutOfStudioWorkoutHistory",
     "PerformanceSummaryDetail",
     "PerformanceSummaryEntry",
+    "SmsNotificationSettings",
     "StatsResponse",
     "StatsTime",
     "StudioDetail",

otf_api-0.9.2/src/otf_api/models/notifications.py

@@ -0,0 +1,17 @@
+from pydantic import Field
+
+from otf_api.models.base import OtfItemBase
+
+
+class SmsNotificationSettings(OtfItemBase):
+    is_promotional_sms_opt_in: bool | None = Field(None, alias="isPromotionalSmsOptIn")
+    is_transactional_sms_opt_in: bool | None = Field(None, alias="isTransactionalSmsOptIn")
+    is_promotional_phone_opt_in: bool | None = Field(None, alias="isPromotionalPhoneOptIn")
+    is_transactional_phone_opt_in: bool | None = Field(None, alias="isTransactionalPhoneOptIn")
+
+
+class EmailNotificationSettings(OtfItemBase):
+    is_system_email_opt_in: bool | None = Field(None, alias="isSystemEmailOptIn")
+    is_promotional_email_opt_in: bool | None = Field(None, alias="isPromotionalEmailOptIn")
+    is_transactional_email_opt_in: bool | None = Field(None, alias="isTransactionalEmailOptIn")
+    email: str | None = None

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/models/performance_summary_detail.py

@@ -68,11 +68,16 @@ class Rower(BaseEquipment):
 
 
 class PerformanceSummaryDetail(OtfItemBase):
-    id: str
+    class_history_uuid: str = Field(..., alias="id")
     class_name: str | None = Field(None, alias=AliasPath("class", "name"))
     class_starts_at: datetime | None = Field(None, alias=AliasPath("class", "starts_at_local"))
 
-    ratable: bool | None = None
+    ratable: bool | None = Field(
+        None,
+        exclude=True,
+        repr=False,
+        description="Seems to be inaccurate, not reflecting ratable from `PerformanceSummaryEntry`",
+    )
     calories_burned: int | None = Field(None, alias=AliasPath("details", "calories_burned"))
     splat_points: int | None = Field(None, alias=AliasPath("details", "splat_points"))
     step_count: int | None = Field(None, alias=AliasPath("details", "step_count"))

{otf_api-0.9.0 → otf_api-0.9.2}/src/otf_api/models/performance_summary_list.py

@@ -33,7 +33,7 @@ class ClassRating(OtfItemBase):
 
 
 class PerformanceSummaryEntry(OtfItemBase):
-    id: str = Field(..., alias="id")
+    class_history_uuid: str = Field(..., alias="id")
     calories_burned: int | None = Field(None, alias=AliasPath("details", "calories_burned"))
     splat_points: int | None = Field(None, alias=AliasPath("details", "splat_points"))
     step_count: int | None = Field(None, alias=AliasPath("details", "step_count"))

otf_api-0.9.0/README.md

@@ -1,21 +0,0 @@
-Simple API client for interacting with the OrangeTheory Fitness APIs.
-
-Review the [documentation](https://otf-api.readthedocs.io/en/stable/).
-
-
-This library allows access to the OrangeTheory API to retrieve workouts and performance data, class schedules, studio information, and bookings.
-
-## Installation
-```bash
-pip install otf-api
-```
-
-## Overview
-
-To use the API, you need to create an instance of the `Otf` class, providing your email address and password. This will authenticate you with the API and allow you to make requests. When the `Otf` object is created it automatically grabs your member details and home studio, to simplify the process of making requests.
-
-
-See the [examples](./examples) for more information on how to use the API.
-
-Disclaimer:
-This project is in no way affiliated with OrangeTheory Fitness.