Improve type safety with specialized dictionary types

Replace generic Optional[Dict[str, Any]] with specialized type aliases throughout the codebase:
1. ParamDict for query string parameters
2. FormDataDict for form data parameters
3. JSONDict for JSON data structures

These changes provide better static type checking, improve code readability and maintainability,
and fix all mypy type errors related to dictionary types.

Author: jpstroop

TODO.md

@@ -4,7 +4,8 @@
 
 - Typing
 
-  - Try to get rid of `Optional[Dict[str, Any]]` args
+  - ✅ Try to get rid of `Optional[Dict[str, Any]]` args - replaced with
+    ParamDict, FormDataDict, JSONDict for more type safety
 
 - base.py: reorganize and see what we can move out.
 

fitbit_client/exceptions.py

@@ -6,6 +6,9 @@
 from typing import List
 from typing import Optional
 
+# Local imports
+from fitbit_client.utils.types import JSONDict
+
 
 class FitbitAPIException(Exception):
     """Base exception for all Fitbit API errors"""
@@ -15,7 +18,7 @@ def __init__(
         message: str,
         error_type: str,
         status_code: Optional[int] = None,
-        raw_response: Optional[Dict[str, Any]] = None,
+        raw_response: Optional[JSONDict] = None,
         field_name: Optional[str] = None,
     ):
         self.message = message

fitbit_client/resources/activity.py

@@ -18,6 +18,7 @@
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
 from fitbit_client.utils.types import JSONList
+from fitbit_client.utils.types import ParamDict
 
 
 class ActivityResource(BaseResource):
@@ -88,7 +89,7 @@ def create_activity_goals(
                 field_name="value",
             )
 
-        params = {"type": type.value, "value": value}
+        params: ParamDict = {"type": type.value, "value": value}
         result = self._make_request(
             f"activities/goals/{period.value}.json",
             params=params,
@@ -152,24 +153,26 @@ def create_activity_log(
             - Start time should be in 24-hour format (e.g., "14:30" for 2:30 PM)
         """
         if activity_id:
-            params = {
+            activity_params: ParamDict = {
                 "activityId": activity_id,
                 "startTime": start_time,
                 "durationMillis": duration_millis,
                 "date": date,
             }
             if distance is not None:
-                params["distance"] = distance
+                activity_params["distance"] = distance
                 if distance_unit:
-                    params["distanceUnit"] = distance_unit
+                    activity_params["distanceUnit"] = distance_unit
+            params = activity_params
         elif activity_name and manual_calories:
-            params = {
+            name_params: ParamDict = {
                 "activityName": activity_name,
                 "manualCalories": manual_calories,
                 "startTime": start_time,
                 "durationMillis": duration_millis,
                 "date": date,
             }
+            params = name_params
         else:
             raise MissingParameterException(
                 message="Must provide either activity_id or (activity_name and manual_calories)",
@@ -229,7 +232,7 @@ def get_activity_log_list(
             - The source field indicates whether the activity was logged manually by the user
               or automatically by a Fitbit device
         """
-        params = {"sort": sort.value, "limit": limit, "offset": offset}
+        params: ParamDict = {"sort": sort.value, "limit": limit, "offset": offset}
         if before_date:
             params["beforeDate"] = before_date
         if after_date:
@@ -651,7 +654,9 @@ def get_activity_tcx(
             - Not all activities have TCX data available (e.g., manually logged activities)
             - To check if an activity has GPS data, look for hasGps=True in the activity log
         """
-        params = {"includePartialTCX": include_partial_tcx} if include_partial_tcx else None
+        params: Optional[ParamDict] = (
+            {"includePartialTCX": include_partial_tcx} if include_partial_tcx else None
+        )
         result = self._make_request(
             f"activities/{log_id}.tcx", params=params, user_id=user_id, debug=debug
         )

fitbit_client/resources/base.py

@@ -23,6 +23,7 @@
 from fitbit_client.exceptions import FitbitAPIException
 from fitbit_client.exceptions import STATUS_CODE_EXCEPTIONS
 from fitbit_client.utils.curl_debug_mixin import CurlDebugMixin
+from fitbit_client.utils.types import FormDataDict
 from fitbit_client.utils.types import JSONDict
 from fitbit_client.utils.types import JSONList
 from fitbit_client.utils.types import JSONType
@@ -139,7 +140,7 @@ def _build_url(
             return f"{self.API_BASE}/{api_version}/user/{user_id}/{endpoint}"
         return f"{self.API_BASE}/{api_version}/{endpoint}"
 
-    def _extract_important_fields(self, data: Dict[str, JSONType]) -> Dict[str, int | str]:
+    def _extract_important_fields(self, data: JSONDict) -> Dict[str, JSONType]:
         """
         Extract important fields from response data for logging.
 
@@ -155,7 +156,7 @@ def _extract_important_fields(self, data: Dict[str, JSONType]) -> Dict[str, int
         """
         extracted = {}
 
-        def extract_recursive(d: Dict[str, Any], prefix: str = "") -> None:
+        def extract_recursive(d: JSONDict, prefix: str = "") -> None:
             for key, value in d.items():
                 full_key = f"{prefix}.{key}" if prefix else key
 
@@ -333,10 +334,10 @@ def _handle_error_response(self, response: Response) -> None:
     def _make_request(
         self,
         endpoint: str,
-        data: Optional[Dict[str, Any]] = None,
-        json: Optional[Dict[str, Any]] = None,
-        params: Optional[Dict[str, Any]] = None,
-        headers: Dict[str, Any] = {},
+        data: Optional[FormDataDict] = None,
+        json: Optional[JSONDict] = None,
+        params: Optional[ParamDict] = None,
+        headers: Dict[str, str] = {},
         user_id: str = "-",
         requires_user_id: bool = True,
         http_method: str = "GET",
@@ -363,7 +364,7 @@ def _make_request(
 
         Returns:
             JSONType: The API response in one of these formats:
-                - Dict[str, Any]: For most JSON object responses
+                - JSONDict: For most JSON object responses
                 - List[Any]: For endpoints that return JSON arrays
                 - str: For XML/TCX responses
                 - None: For successful DELETE operations or debug mode

fitbit_client/resources/body.py

@@ -9,6 +9,7 @@
 from fitbit_client.resources.constants import BodyGoalType
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class BodyResource(BaseResource):
@@ -101,7 +102,7 @@ def create_bodyfat_log(
             The 'source' field will be set to "API" for entries created through this endpoint.
             Multiple entries can be logged for the same day with different timestamps.
         """
-        params = {"fat": fat, "date": date}
+        params: ParamDict = {"fat": fat, "date": date}
         if time:
             params["time"] = time
         result = self._make_request(
@@ -151,7 +152,7 @@ def create_weight_goal(
             - If target > start: "GAIN"
             - If target = start: "MAINTAIN"
         """
-        params = {"startDate": start_date, "startWeight": start_weight}
+        params: ParamDict = {"startDate": start_date, "startWeight": start_weight}
         if weight is not None:
             params["weight"] = weight
         result = self._make_request(
@@ -208,7 +209,7 @@ def create_weight_log(
             The 'source' field will be set to "API" for entries created through this endpoint.
             Multiple weight entries can be logged for the same day with different timestamps.
         """
-        params = {"weight": weight, "date": date}
+        params: ParamDict = {"weight": weight, "date": date}
         if time:
             params["time"] = time
         result = self._make_request(

fitbit_client/resources/electrocardiogram.py

@@ -12,6 +12,7 @@
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class ElectrocardiogramResource(BaseResource):
@@ -56,7 +57,7 @@ def get_ecg_log_list(
         offset: int = 0,
         user_id: str = "-",
         debug: bool = False,
-    ) -> Dict[str, Any]:
+    ) -> JSONDict:
         """Returns a list of user's ECG log entries before or after a given day.
 
         API Reference: https://dev.fitbit.com/build/reference/web-api/electrocardiogram/get-ecg-log-list/
@@ -92,7 +93,7 @@ def get_ecg_log_list(
             - resultClassification indicates the assessment outcome (normal, afib, inconclusive)
             - For research purposes only, not for clinical or diagnostic use
         """
-        params = {"sort": sort.value, "limit": limit, "offset": offset}
+        params: ParamDict = {"sort": sort.value, "limit": limit, "offset": offset}
 
         if before_date:
             params["beforeDate"] = before_date

fitbit_client/resources/heartrate_timeseries.py

@@ -12,6 +12,7 @@
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.date_validation import validate_date_range_params
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class HeartrateTimeSeriesResource(BaseResource):
@@ -105,7 +106,7 @@ def get_heartrate_timeseries_by_date(
                 message="Only 'UTC' timezone is supported", field_name="timezone"
             )
 
-        params = {"timezone": timezone} if timezone else None
+        params: Optional[ParamDict] = {"timezone": timezone} if timezone else None
         result = self._make_request(
             f"activities/heart/date/{date}/{period.value}.json",
             params=params,
@@ -169,7 +170,7 @@ def get_heartrate_timeseries_by_date_range(
                 message="Only 'UTC' timezone is supported", field_name="timezone"
             )
 
-        params = {"timezone": timezone} if timezone else None
+        params: Optional[ParamDict] = {"timezone": timezone} if timezone else None
         result = self._make_request(
             f"activities/heart/date/{start_date}/{end_date}.json",
             params=params,

fitbit_client/resources/irregular_rhythm_notifications.py

@@ -10,6 +10,7 @@
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class IrregularRhythmNotificationsResource(BaseResource):
@@ -93,7 +94,7 @@ def get_irn_alerts_list(
             - The alertTime is when the notification was generated, while detectedTime is
               when the irregular rhythm was detected (usually during sleep)
         """
-        params = {"sort": sort.value, "limit": limit, "offset": offset}
+        params: ParamDict = {"sort": sort.value, "limit": limit, "offset": offset}
 
         if before_date:
             params["beforeDate"] = before_date

fitbit_client/resources/nutrition.py

@@ -384,10 +384,15 @@ def create_meal(
             Food IDs can be obtained from food search results or the user's custom foods.
         """
         # snakes to camels
-        foods = [{to_camel_case(k): v for k, v in d.items()} for d in foods]
-        data = {"name": name, "description": description, "mealFoods": foods}
+        foods_list = [{to_camel_case(k): v for k, v in d.items()} for d in foods]
+        # Use cast to handle the complex structure
+        data_dict = {"name": name, "description": description, "mealFoods": foods_list}
         result = self._make_request(
-            "meals.json", json=data, user_id=user_id, http_method="POST", debug=debug
+            "meals.json",
+            json=cast(JSONDict, data_dict),
+            user_id=user_id,
+            http_method="POST",
+            debug=debug,
         )
         return cast(JSONDict, result)
 
@@ -1179,10 +1184,15 @@ def update_meal(
             Meal IDs can be obtained from the get_meals method. Updating a meal does not
             affect any food logs that were previously created using this meal.
         """
-        foods = [{to_camel_case(k): v for k, v in d.items()} for d in foods]
-        data = {"name": name, "description": description, "mealFoods": foods}
+        foods_list = [{to_camel_case(k): v for k, v in d.items()} for d in foods]
+        # Use cast to handle the complex structure
+        data_dict = {"name": name, "description": description, "mealFoods": foods_list}
         result = self._make_request(
-            f"meals/{meal_id}.json", json=data, user_id=user_id, http_method="POST", debug=debug
+            f"meals/{meal_id}.json",
+            json=cast(JSONDict, data_dict),
+            user_id=user_id,
+            http_method="POST",
+            debug=debug,
         )
         return cast(JSONDict, result)
 

fitbit_client/resources/sleep.py

@@ -14,6 +14,7 @@
 from fitbit_client.utils.date_validation import validate_date_range_params
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class SleepResource(BaseResource):
@@ -124,7 +125,7 @@ def create_sleep_log(
                 message="duration_millis must be positive", field_name="duration_millis"
             )
 
-        params = {"startTime": start_time, "duration": duration_millis, "date": date}
+        params: ParamDict = {"startTime": start_time, "duration": duration_millis, "date": date}
         result = self._make_request(
             "sleep.json",
             params=params,
@@ -355,7 +356,7 @@ def get_sleep_log_list(
 
             This endpoint uses API version 1.2, unlike most other Fitbit API endpoints.
         """
-        params = {"sort": sort.value, "limit": limit, "offset": offset}
+        params: ParamDict = {"sort": sort.value, "limit": limit, "offset": offset}
         if before_date:
             params["beforeDate"] = before_date
         if after_date: