Refactor pagination to use 'next' URL

- Completely redesigned pagination mechanism to use the 'next' URL provided by the Fitbit API
- Added ID tracking to prevent duplicate data
- Fixed hanging tests in test_error_handling.py
- Added comprehensive tests for all paginated endpoints
- Implemented support for all four paginated endpoints: sleep logs, activity logs, ECG logs, and IRN alerts
- Created pagination documentation in docs/PAGINATION.md

Author: jpstroop

README.md

@@ -156,6 +156,54 @@ between sessions. If provided, the client will:
 3. Set Callback URL to "https://localhost:8080" (or your preferred local URL)
 4. Copy your Client ID and Client Secret
 
+## Pagination
+
+Some Fitbit API endpoints support pagination for large result sets. With this
+client, you can work with paginated endpoints in two ways:
+
+```python
+# Standard way - get a single page of results
+sleep_logs = client.get_sleep_log_list(before_date="2025-01-01")
+
+# Iterator way - get an iterator that fetches all pages automatically
+for page in client.get_sleep_log_list(before_date="2025-01-01", as_iterator=True):
+    for sleep_entry in page["sleep"]:
+        print(sleep_entry["logId"])
+```
+
+Endpoints that support pagination:
+
+- `get_sleep_log_list()`
+- `get_activity_log_list()`
+- `get_ecg_log_list()`
+- `get_irn_alerts_list()`
+
+For more details, see [PAGINATION.md](docs/PAGINATION.md).
+
+## Rate Limiting
+
+The client includes automatic retry handling for rate-limited requests. When a
+rate limit is encountered, the client will:
+
+1. Log the rate limit event
+2. Wait using an exponential backoff strategy
+3. Automatically retry the request
+
+You can configure rate limiting behavior:
+
+```python
+client = FitbitClient(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    redirect_uri="https://localhost:8080",
+    max_retries=5,                # Maximum number of retry attempts (default: 3)
+    retry_after_seconds=30,       # Base wait time in seconds (default: 60)
+    retry_backoff_factor=2.0      # Multiplier for successive waits (default: 1.5)
+)
+```
+
+For more details, see [RATE_LIMITING.md](docs/RATE_LIMITING.md).
+
 ## Additional Documentation
 
 ### For API Library Users
@@ -165,6 +213,9 @@ between sessions. If provided, the client will:
 - [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
+- [PAGINATION.md](docs/PAGINATION.md): Working with paginated endpoints
+- [RATE_LIMITING.md](docs/RATE_LIMITING.md): Rate limit handling and
+  configuration
 
 It's also worth reviewing
 [Fitbit's Best Practices](https://dev.fitbit.com/build/reference/web-api/developer-guide/best-practices/)

docs/PAGINATION.md

@@ -0,0 +1,89 @@
+# Pagination
+
+Some Fitbit API endpoints return potentially large result sets and support
+pagination. This library provides an easy way to work with these paginated
+endpoints.
+
+## Supported Endpoints
+
+The following endpoints support pagination:
+
+- `client.get_sleep_log_list()`
+- `client.get_activity_log_list()`
+- `client.get_ecg_log_list()`
+- `client.get_irn_alerts_list()`
+
+## Usage
+
+### Standard Mode
+
+By default, all endpoints return a single page of results with pagination
+metadata:
+
+```python
+# Get a single page of sleep logs
+sleep_data = client.get_sleep_log_list(
+    before_date="2025-01-01",
+    sort=SortDirection.DESCENDING,
+    limit=10
+)
+
+# Access the pagination metadata
+pagination_info = sleep_data["pagination"]
+has_next_page = "next" in pagination_info and bool(pagination_info["next"])
+
+# Process the page data
+for sleep_entry in sleep_data["sleep"]:
+    print(f"Sleep log ID: {sleep_entry['logId']}")
+```
+
+### Iterator Mode
+
+When you need to process multiple pages of data, use iterator mode:
+
+```python
+iterator = client.get_sleep_log_list(
+    before_date="2025-01-01",
+    sort=SortDirection.DESCENDING,
+    limit=10,
+    as_iterator=True # Creates an iterator for all pages
+)
+
+# Process all pages - the iterator fetches new pages as needed
+for page in iterator:
+    # Each page has the same structure as the standard response
+    for sleep_entry in page["sleep"]:
+        print(f"Sleep log ID: {sleep_entry['logId']}")
+```
+
+## Pagination Parameters
+
+Different endpoints support different pagination parameters, but they generally
+follow these patterns:
+
+| Parameter     | Description                     | Constraints                                                 |
+| ------------- | ------------------------------- | ----------------------------------------------------------- |
+| `before_date` | Return entries before this date | Must use with `sort=SortDirection.DESCENDING`               |
+| `after_date`  | Return entries after this date  | Must use with `sort=SortDirection.ASCENDING`                |
+| `limit`       | Maximum items per page          | Varies by endpoint (10-100)                                 |
+| `offset`      | Starting position               | Usually only `0` is supported                               |
+| `sort`        | Sort direction                  | Use `SortDirection.ASCENDING` or `SortDirection.DESCENDING` |
+
+## Endpoint-Specific Notes
+
+Each paginated endpoint has specific constraints:
+
+### `get_sleep_log_list`
+
+- Max limit: 100 entries per page
+- Date filtering: `before_date` or `after_date` (must specify one but not both)
+
+### `get_activity_log_list`
+
+- Max limit: 100 entries per page
+- Date filtering: `before_date` or `after_date` (must specify one but not both)
+
+### `get_ecg_log_list` and `get_irn_alerts_list`
+
+- Max limit: 10 entries per page
+- Only supports `offset=0`

docs/RATE_LIMITING.md

@@ -0,0 +1,105 @@
+# Rate Limiting
+
+The Fitbit API enforces rate limits to prevent overuse. When you exceed these
+limits, the API returns a `429 Too Many Requests` error. We attempt to include
+retry mechanisms to handle rate limiting gracefully.
+
+## How It Works
+
+When a rate limit is encountered, the client will:
+
+1. Log a warning message with details about the rate limit
+2. Wait for an appropriate amount of time using exponential backoff
+3. Automatically retry the request (up to a configurable maximm)
+4. Either return the successful response or raise an exceptione after exhausting
+   retries
+
+All of this should happen transparently and without manual intervention.
+
+## Configuration
+
+Configure rate limiting behavior when creating the client:
+
+```python
+from fitbit_client import FitbitClient
+
+client = FitbitClient(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    redirect_uri="https://localhost:8080",
+    
+    # Rate limiting options (all optional)
+    max_retries=5,                # Maximum retry attempts (default: 3)
+    retry_after_seconds=10,       # Base wait time in seconds (default: 5)
+    retry_backoff_factor=2.0      # Multiplier for successive waits (default: 1.5)
+)
+```
+
+## Exponential Backoff
+
+The wait time between retries increases exponentially to avoid overwhelming the
+API. The formula is:
+
+```
+retry_time = retry_after_seconds * (retry_backoff_factor ^ retry_count)
+```
+
+With the default settings:
+
+- First retry: Wait 60 seconds
+- Second retry: Wait 90 seconds (60 * 1.5)
+- Third retry: Wait 135 seconds (60 * 1.5²)
+
+## Fitbit API Rate Limits
+
+The Fitbit API has different rate limits for different endpoints:
+
+- **User-level rate limits**: Up to 150 API calls per hour per user
+- **Client-level rate limits**: For applications with many users
+
+Refer to the
+[Fitbit API Rate Limits documentation](https://dev.fitbit.com/build/reference/web-api/developer-guide/application-design/#Rate-Limits)
+for the most current information.
+
+## Logging
+
+Rate limit events are logged to the standard application logger. To capture
+these logs:
+
+```python
+import logging
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+
+# Use the client
+client = FitbitClient(...)
+```
+
+You'll see log messages like:
+
+```
+WARNING:fitbit_client.SleepResource:Rate limit exceeded for get_sleep_log_list to sleep/list.json. Retrying in 60 seconds. (2 retries remaining)
+```
+
+## Handling Unrecoverable Rate Limits
+
+If all retry attempts are exhausted, the client will raise a
+`RateLimitExceededException`. You can catch this exception to implement your own
+fallback logic:
+
+```python
+from fitbit_client import FitbitClient
+from fitbit_client.exceptions import RateLimitExceededException
+
+client = FitbitClient(...)
+
+try:
+    # Make API request
+    data = client.get_activity_log_list(before_date="2025-01-01")
+    # Process data
+except RateLimitExceededException as e:
+    # Handle unrecoverable rate limit
+    print(f"Rate limit exceeded even after retries: {e}")
+    # Implement fallback logic
+```