Corruption cleanup; merges a few commits:

- Ignore TODO
- Bring back resource method aliases
- Streamline README
- Improve documentation organization and readability:
    - Split NAMING_AND_TYPING.md into TYPES.md and NAMING.md
    - Split VALIDATIONS_AND_EXCEPTIONS.md into VALIDATIONS.md and ERROR_HANDLING.md
    - Update README.md with organized documentation links
    - Fix intraday data support information in DEVELOPMENT.md
    - Add information about disabling data logging to LOGGING.md
    - Update TODO.md to reflect completed documentation work

Author: jpstroop

.gitignore

@@ -44,6 +44,7 @@ coverage.xml
 htmlcov/
 .pytest_cache/
 .mypy_cache/
+*,cover
 
 # Mac
 .DS_Store
@@ -57,3 +58,5 @@ _scripts
 _cov_html
 secrets.json
 tokens.json
+TODO.mdø
+

README.md

@@ -48,7 +48,10 @@ try:
     client.authenticate()
 
     # Make a request (e.g., get user profile)
+    # You can access resources directly:
     profile = client.user.get_profile()
+    # Or use method aliases for shorter syntax:
+    profile = client.get_profile()
     print(dumps(profile, indent=2))
 
 except Exception as e:
@@ -59,63 +62,109 @@ The response will always be the body of the API response, and is almost always a
 `Dict`, `List` or `None`. `nutrition.get_activity_tcx` is the exception. It
 returns XML (as a `str`).
 
-## Authentication Methods
+## Method Aliases
 
-### 1. Automatic (Recommended)
-
-Uses a local callback server to automatically handle the OAuth2 flow:
+All resource methods are available directly from the client instance. This means
+you can use:
 
 ```python
-client = FitbitClient(
-    client_id="YOUR_CLIENT_ID",
-    client_secret="YOUR_CLIENT_SECRET",
-    redirect_uri="https://localhost:8080",
-    use_callback_server=True  # default is True
-)
+# Short form with method aliases
+client.get_profile()
+client.get_daily_activity_summary(date="2025-03-06")
+client.get_sleep_log_by_date(date="2025-03-06")
+```
 
-# Will open browser and handle callback automatically
-client.authenticate()
+Instead of the longer form:
+
+```python
+# Standard resource access
+client.user.get_profile()
+client.activity.get_daily_activity_summary(date="2025-03-06")
+client.sleep.get_sleep_log_by_date(date="2025-03-06")
 ```
 
-### 2. Manual URL Copy/Paste
+Both approaches are equivalent, but aliases provide a more concise syntax.
 
-If you prefer not to use a local server:
+## Authentication
+
+Uses a local callback server to automatically handle the OAuth2 flow:
 
 ```python
 client = FitbitClient(
     client_id="YOUR_CLIENT_ID",
     client_secret="YOUR_CLIENT_SECRET",
     redirect_uri="YOUR_REGISTERED_REDIRECT_URI",
-    token_cache_path="/tmp/fb_tokens.json",
-    use_callback_server=True
+    token_cache_path="/tmp/fb_tokens.json"  # Optional: saves tokens between sessions
+    redirect_uri="YOUR_REGISTERED_REDIRECT_URI",
+    token_cache_path="/tmp/fb_tokens.json"  # Optional: saves tokens between sessions
 )
 
-# Will open a browser and start a server to complete the flow (default), or 
-# prompt you on the command line to copy/paste the callback URL from the 
-# browser (see `use_callback_server`)
+# Will open browser and handle callback automatically
 client.authenticate()
 ```
 
+The `token_cache_path` parameter allows you to persist authentication tokens
+between sessions. If provided, the client will:
+
+1. Load existing tokens from this file if available (avoiding re-authentication)
+
+2. Save new or refreshed tokens to this file automatically
+
+3. Handle token refresh when expired tokens are detected The `token_cache_path`
+   parameter allows you to persist authentication tokens between sessions. If
+   provided, the client will:
+
+4. Load existing tokens from this file if available (avoiding re-authentication)
+
+5. Save new or refreshed tokens to this file automatically
+
+6. Handle token refresh when expired tokens are detected
+
 ## Setting Up Your Fitbit App
 
 1. Go to dev.fitbit.com and create a new application
 2. Set OAuth 2.0 Application Type to "Personal"
-3. Set Callback URL to:
-   - For automatic method: "https://localhost:8080"
-   - For manual method: Your preferred redirect URI
-4. Copy your Client ID and Client Secret
-
-Additional documentation:
-
-- To understand the logging implemementation, see [LOGGING](docs/LOGGING.md)
-- To understand validations and the exception hierarchy, see
-  [VALIDATIONS_AND_EXCEPTIONS](docs/VALIDATIONS_AND_EXCEPTIONS.md)
-- It's work checking out
-  [Fitbit's Best Practices](https://dev.fitbit.com/build/reference/web-api/developer-guide/best-practices/)
-- For some general development guidelines, see
-  [DEVELOPMENT](docs/DEVELOPMENT.md).
-- For style guidelines (mostly enforced through varius linters and formatters)
-  see [STYLE](docs/STYLE.md).
+3. Set Callback URL to "https://localhost:8080" (or your preferred local URL)
+4. Set Callback URL to "https://localhost:8080" (or your preferred local URL)
+5. Copy your Client ID and Client Secret
+
+## Additional Documentation
+
+### For API Library Users
+
+- [LOGGING.md](docs/LOGGING.md): Understanding the dual-logger system
+- [TYPES.md](docs/TYPES.md): JSON type system and method return types
+- [NAMING.md](docs/NAMING.md): API method naming conventions
+- [VALIDATIONS.md](docs/VALIDATIONS.md): Input parameter validation
+- [ERROR_HANDLING.md](docs/ERROR_HANDLING.md): Exception hierarchy and handling
+
+It's also worth reviewing
+[Fitbit's Best Practices](https://dev.fitbit.com/build/reference/web-api/developer-guide/best-practices/)
+for API usage.
+
+### Project Best Practices
+
+- [DEVELOPMENT.md](docs/DEVELOPMENT.md): Development environment and guidelines
+- [STYLE.md](docs/STYLE.md): Code style and formatting standards
+
+## Additional Documentation
+
+### For API Library Users
+
+- [LOGGING.md](docs/LOGGING.md): Understanding the dual-logger system
+- [TYPES.md](docs/TYPES.md): JSON type system and method return types
+- [NAMING.md](docs/NAMING.md): API method naming conventions
+- [VALIDATIONS.md](docs/VALIDATIONS.md): Input parameter validation
+- [ERROR_HANDLING.md](docs/ERROR_HANDLING.md): Exception hierarchy and handling
+
+It's also worth reviewing
+[Fitbit's Best Practices](https://dev.fitbit.com/build/reference/web-api/developer-guide/best-practices/)
+for API usage.
+
+### Project Best Practices
+
+- [DEVELOPMENT.md](docs/DEVELOPMENT.md): Development environment and guidelines
+- [STYLE.md](docs/STYLE.md): Code style and formatting standards
 
 ## Important Note - Subscription Support
 
@@ -124,9 +173,20 @@ This client does not currently support the
 and
 [deletion](https://dev.fitbit.com/build/reference/web-api/subscription/delete-subscription/)
 of
-[webhook subscrptions](https://dev.fitbit.com/build/reference/web-api/developer-guide/using-subscriptions/).
-The methods are implemented in comments and _should_ work, but I have not had a
-chance to verify a user confirm this.
+[webhook subscriptions](https://dev.fitbit.com/build/reference/web-api/developer-guide/using-subscriptions/).
+The methods are implemented in comments and should work, but I have not had a
+chance to verify them since this requires a publicly accessible server to
+receive webhook notifications.
+
+If you're using this library with subscriptions and would like to help test and
+implement this functionality, please open an issue or pull request!
+[webhook subscriptions](https://dev.fitbit.com/build/reference/web-api/developer-guide/using-subscriptions/).
+The methods are implemented in comments and should work, but I have not had a
+chance to verify them since this requires a publicly accessible server to
+receive webhook notifications.
+
+If you're using this library with subscriptions and would like to help test and
+implement this functionality, please open an issue or pull request!
 
 ## License
 

TODO.md

@@ -1,49 +1,31 @@
 # Project TODO and Notes
 
-## Refactoring TODOs
+## TODOs:
 
-- Typing
+- PyPi deployment
 
-  - Try to get rid of `Optional[Dict[str, Any]]` args
+- For all `create_...`methods, add the ID from the response to logs and maybe
+  something human readable, like the first n characters of the name??. Right
+  now:
+
+```log
+[2025-02-05 06:09:34,828] INFO [fitbit_client.NutritionResource] create_food_log succeeded for foods/log.json (status 201)
+```
 
 - base.py: reorganize and see what we can move out.
 
   - Rename to `_base`? Files it first, makes it clearer that everything in it is
     private
-  - Move the methods for building `curl` commands into a mixin? It's a lot of
-    code for an isolated and tightly scoped feature.
-  - refactor `_make_request`.
-    - do we need both `data` and `json`? Also, could we simplify a lot of typing
-      if we separated GET, POST, and DELETE methods? Maybe even a separate,
-      second non-auth GET? Could use `@overload`
-    - we had to makee a `ParamDict` type in `nutrition.py`. Use this everywhere?
-    - start by looking at how many methods use which params
 
 - client.py:
 
   - Creat and Test that all methods have an alias in `Client` and that the
     signatures match
 
-```python
-if not food_id and not (food_name and calories):
-    raise ClientValidationException(
-        "Must provide either food_id or (food_name and calories)"
-    )
-```
-
-- nutrition.py:
-- It doesn't seem like this should be passing tests when CALORIES is not an int:
+- CI:
 
-```python
-        # Handle both enum and string nutritional values
-       for key, value in nutritional_values.items():
-           if isinstance(key, NutritionalValue):
-               params[key.value] = float(value)
-           else:
-               params[str(key)] = float(value)
-```
-
-see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
+* Read and implement:
+  https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql
 
 - exceptions.py Consider:
   - Add automatic token refresh for ExpiredTokenException
@@ -77,14 +59,6 @@ see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
     be reused.
   - We may need a public version of a generic `make_request` method.
 
-- For all `create_...`methods, add the ID from the response to logs and maybe
-  something human readable, like the first n characters of the name??. Right
-  now:
-
-```log
-[2025-02-05 06:09:34,828] INFO [fitbit_client.NutritionResource] create_food_log succeeded for foods/log.json (status 201)
-```
-
 - Form to change scopes are part of OAuth flow? Maybe get rid of the cut and
   paste method altogether? It's less to test...
 
@@ -101,19 +75,4 @@ see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
     one. (there might be several of these that make sense--just take an ID and
     then the signature of the "create" method).
 
-- PyPI deployment
-
 - Enum for units? (it'll be big, maybe just common ones?)
-
-## CI/CD/Linting
-
-- GitHub Actions Setup
-
-  - Linting
-    - black
-    - isort
-    - mdformat
-    - mypy
-  - Test running (TBD)
-  - Coverage reporting (TBD)
-  - Automated PyPI deployment