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
 

docs/DEVELOPMENT.md

@@ -16,6 +16,9 @@
 - [Logging System](#logging-system)
   - [Application Logger](#application-logger)
   - [Data Logger](#data-logger)
+- [API Design](#api-design)
+  - [Resource-Based API](#resource-based-api)
+  - [Method Aliases](#method-aliases)
 - [Testing](#testing)
   - [Test Organization](#test-organization)
   - [Standard Test Fixtures](#standard-test-fixtures)
@@ -235,6 +238,63 @@ Data log entries contain:
 This logging system provides both operational visibility through the application
 logger and structured data capture through the data logger.
 
+## API Design
+
+The client implements a dual-level API design pattern that balances both
+organization and ease-of-use.
+
+### Resource-Based API
+
+The primary API structure is resource-based, organizing related endpoints into
+dedicated resource classes:
+
+- `client.user` - User profile and badges endpoints
+- `client.activity` - Activity tracking, goals, and summaries
+- `client.sleep` - Sleep logs and goals
+- etc.
+
+This organization provides a clean separation of concerns and makes the code
+more maintainable by grouping related functionality.
+
+### Method Aliases
+
+To improve developer experience, all resource methods are also available
+directly from the client instance through aliases. This means developers can
+choose between two equivalent approaches:
+
+```python
+# Standard resource-based access
+client.user.get_profile()
+client.activity.get_daily_activity_summary(date="2025-03-06")
+
+# Direct access via method aliases
+client.get_profile()
+client.get_daily_activity_summary(date="2025-03-06")
+```
+
+#### Rationale for Method Aliases
+
+Method aliases were implemented for several important reasons:
+
+1. **Reduced Verbosity**: Typing `client.resource_name.method_name(...)` with
+   many parameters can be tedious, especially when used frequently.
+
+2. **Flatter API Surface**: Many modern APIs prefer a flatter design that avoids
+   deep nesting, making the API more straightforward to use.
+
+3. **Method Name Uniqueness**: All resource methods in the Fitbit API have
+   unique names (e.g., there's only one `get_profile()` method), making it safe
+   to expose these methods directly on the client.
+
+4. **Preserve Both Options**: By maintaining both the resource-based access and
+   direct aliases, developers can choose the approach that best fits their needs
+   \- organization or conciseness.
+
+All method aliases are set up in the `_setup_method_aliases()` method in the
+`FitbitClient` class, which is called during initialization. Each alias is a
+direct reference to the corresponding resource method, ensuring consistent
+behavior regardless of how the method is accessed.
+
 ## Testing
 
 The project uses pytest for testing and follows a consistent testing approach
@@ -339,18 +399,32 @@ TODO
 - Use issue templates when reporting bugs
 - Include Python version and environment details in bug reports
 
-## Scope and Limitations - Intraday Data Support
+## Intraday Data Support
 
-This client explicitly does not implement intraday data endpoints (detailed
-heart rate, steps, etc). These endpoints:
+This client implements intraday data endpoints (detailed heart rate, steps, etc)
+through the `IntradayResource` class. These endpoints:
 
 - Require special access from Fitbit (typically limited to research
   applications)
 - Have different rate limits than standard endpoints
-- Need additional OAuth2 scopes
-- Often require institutional review board (IRB) approval
-
-If you need intraday data access:
-
-1. Apply through Fitbit's developer portal
-2. Pull requests welcome!
+- Need additional OAuth2 scopes (specifically the 'activity' and 'heartrate'
+  scopes)
+- Often require institutional review board (IRB) approval for research
+  applications
+
+To use intraday data:
+
+1. Apply for intraday access through the
+   [Fitbit developer portal](https://dev.fitbit.com/)
+2. Ensure your application requests the appropriate scopes
+3. Use the intraday methods with appropriate detail level parameters:
+   ```python
+   client.intraday.get_heartrate_intraday_by_date(
+       date="today",
+       detail_level="1min"  # or "1sec" depending on your access level
+   )
+   ```
+
+See the
+[Intraday API documentation](https://dev.fitbit.com/build/reference/web-api/intraday/)
+for more details on available endpoints and access requirements.