v1.1.0: auto-retry with backoff, pagination helpers, split timeouts, typed returns

- Automatic retry with exponential backoff + jitter on 429, 5xx, and network errors
- Configurable retry policy (max_retries, backoff_multiplier, initial_retry_delay, max_retry_delay)
- paginate() and paginate_pages() generators for auto-pagination
- Split timeouts (connect_timeout, read_timeout) with tuple support
- Typed return values on all 70+ resource methods (specific TypedDicts)
- rate_limit_info property exposes last 429 state
- Updated README with new feature documentation

Author: restocked

README.md

@@ -37,10 +37,13 @@ next_page = client.user.get_followers(
 ## Features
 
 - **70+ endpoints** covering users, tweets, posts, interactions, DMs, communities, spaces, and search
-- **Full type hints** with TypedDict definitions for IDE autocomplete
+- **Full type hints** with TypedDict response types for IDE autocomplete
+- **Automatic retry with backoff** on rate limits (429) and server errors (5xx)
+- **Auto-pagination helpers** — iterate all pages with a simple `for` loop
 - **Solid error handling** with typed exceptions (`RateLimitError`, `NotFoundError`, etc.)
+- **Rate limit awareness** — `retry_after` respected automatically, state exposed via `client.rate_limit_info`
+- **Split timeouts** — separate connect and read timeouts
 - **Single dependency** — `requests` only
-- **Pagination support** with cursor-based navigation
 - **Python 3.9+** compatible
 
 ## API Reference
@@ -170,12 +173,71 @@ next_page = client.user.get_followers(
 | `client.dm.get_dm_user_updates(auth_token=..., cursor=...)` | DM user updates |
 | `client.dm.accept_conversation(auth_token=..., conversation_id=...)` | Accept request |
 
+## Auto-Pagination
+
+Use the `paginate()` and `paginate_pages()` helpers to iterate through all pages automatically:
+
+```python
+from tweetapi import TweetAPI, paginate, paginate_pages
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+# Iterate individual items across all pages
+for user in paginate(
+    lambda cursor: client.user.get_followers(user_id="123456", cursor=cursor),
+):
+    print(user["username"])
+
+# Iterate full pages (access page-level data)
+for page in paginate_pages(
+    lambda cursor: client.explore.search(query="bitcoin", type="Latest", cursor=cursor),
+    max_pages=5,  # optional: limit number of pages
+):
+    print(f"Got {len(page['data'])} results")
+    print(f"Next cursor: {page['pagination']['nextCursor']}")
+```
+
+Works with any paginated endpoint — followers, tweets, search results, list members, community posts, etc.
+
+## Automatic Retry with Backoff
+
+The SDK automatically retries on transient errors with exponential backoff:
+
+- **429 (Rate Limit)** — waits the `retry_after` duration from the API, then retries
+- **5xx (Server Error)** — retries with exponential backoff + jitter
+- **Network errors** — retries on timeouts and connection failures
+- **4xx (Client Error)** — never retried (400, 401, 403, 404 fail immediately)
+
+Default: 3 retries, 2x backoff, 1s initial delay, 30s max delay.
+
+```python
+# Customize retry behavior
+client = TweetAPI(
+    api_key="YOUR_API_KEY",
+    max_retries=5,             # default: 3
+    initial_retry_delay=2.0,   # default: 1.0 (seconds)
+    backoff_multiplier=3.0,    # default: 2.0
+    max_retry_delay=60.0,      # default: 30.0 (seconds)
+)
+
+# Disable retries entirely
+client = TweetAPI(api_key="YOUR_API_KEY", max_retries=0)
+```
+
+### Rate Limit Awareness
+
+After a 429 response, the SDK exposes the last known rate limit state:
+
+```python
+print(client.rate_limit_info)
+# {"retry_after": 30, "timestamp": 1712345678.0} — or None if no 429 encountered
+```
+
 ## Error Handling
 
-The SDK throws typed exceptions you can catch and handle:
+The SDK raises typed exceptions you can catch and handle. With automatic retries enabled (default), you'll only see these after all retry attempts are exhausted:
 
 ```python
-import time
 from tweetapi import (
     TweetAPI,
     TweetAPIError,
@@ -192,9 +254,7 @@ client = TweetAPI(api_key="YOUR_API_KEY")
 try:
     user = client.user.get_by_username(username="elonmusk")
 except RateLimitError as e:
-    # Wait and retry
     print(f"Rate limited. Retry in {e.retry_after}s")
-    time.sleep(e.retry_after)
 except NotFoundError:
     print("User not found")
 except AuthenticationError:
@@ -206,7 +266,6 @@ except ServerError:
 except NetworkError:
     print("Network error — check your connection")
 except TweetAPIError as e:
-    # Catch-all for any other API error
     print(f"Error [{e.code}]: {e.message}")
 ```
 
@@ -222,8 +281,17 @@ Every error includes:
 client = TweetAPI(
     api_key="YOUR_API_KEY",           # Required
     base_url="https://...",           # Optional (default: https://api.tweetapi.com)
-    timeout=30,                       # Optional (default: 30 seconds)
+    timeout=30,                       # Optional — single value for both connect + read
+    connect_timeout=10.0,             # Optional (default: 10s)
+    read_timeout=30.0,                # Optional (default: 30s)
+    max_retries=3,                    # Optional (default: 3, set 0 to disable)
+    backoff_multiplier=2.0,           # Optional (default: 2.0)
+    initial_retry_delay=1.0,          # Optional (default: 1.0s)
+    max_retry_delay=30.0,             # Optional (default: 30.0s)
 )
+
+# You can also pass a tuple for timeout
+client = TweetAPI(api_key="YOUR_API_KEY", timeout=(5, 30))  # (connect, read)
 ```
 
 ## Requirements

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tweetapi"
-version = "1.0.0"
+version = "1.1.0"
 description = "Official Python SDK for TweetAPI — Twitter/X Data API for developers and researchers"
 readme = "README.md"
 license = "MIT"

tests/test_client.py

@@ -17,8 +17,10 @@
 BASE_URL = "https://api.tweetapi.com"
 
 
-def make_client() -> TweetAPI:
-    return TweetAPI(api_key="test-api-key")
+def make_client(**kwargs) -> TweetAPI:
+    defaults = {"api_key": "test-api-key", "max_retries": 0}
+    defaults.update(kwargs)
+    return TweetAPI(**defaults)
 
 
 class TestClientInit:
@@ -240,6 +242,6 @@ def test_preserves_api_error_code(self):
         assert exc_info.value.code == "ACCOUNT_SUSPENDED"
 
     def test_network_error_on_connection_failure(self):
-        client = TweetAPI(api_key="key", base_url="http://localhost:1")
+        client = TweetAPI(api_key="key", base_url="http://localhost:1", max_retries=0)
         with pytest.raises(NetworkError):
             client.user.get_by_username(username="test")

tests/test_pagination.py

@@ -0,0 +1,101 @@
+"""Tests for auto-pagination helpers."""
+
+import pytest
+
+from tweetapi import paginate, paginate_pages
+
+
+def make_fetcher(pages):
+    """Create a fetcher that returns pre-built pages in sequence."""
+    call_count = [0]
+
+    def fetcher(cursor=None):
+        idx = call_count[0]
+        if idx >= len(pages):
+            raise RuntimeError(f"Unexpected call #{idx + 1}")
+        call_count[0] += 1
+        return pages[idx]
+
+    fetcher.call_count = call_count
+    return fetcher
+
+
+class TestPaginatePages:
+    def test_iterates_all_pages(self):
+        pages_data = [
+            {"data": [{"id": "1"}, {"id": "2"}], "pagination": {"nextCursor": "c2", "prevCursor": None}},
+            {"data": [{"id": "3"}], "pagination": {"nextCursor": "c3", "prevCursor": "c2"}},
+            {"data": [{"id": "4"}], "pagination": {"nextCursor": None, "prevCursor": "c3"}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        result = list(paginate_pages(fetcher))
+        assert len(result) == 3
+        assert fetcher.call_count[0] == 3
+
+    def test_respects_max_pages(self):
+        pages_data = [
+            {"data": [{"id": "1"}], "pagination": {"nextCursor": "c2", "prevCursor": None}},
+            {"data": [{"id": "2"}], "pagination": {"nextCursor": "c3", "prevCursor": "c2"}},
+            {"data": [{"id": "3"}], "pagination": {"nextCursor": None, "prevCursor": "c3"}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        result = list(paginate_pages(fetcher, max_pages=2))
+        assert len(result) == 2
+        assert fetcher.call_count[0] == 2
+
+    def test_single_page_no_next_cursor(self):
+        pages_data = [
+            {"data": [{"id": "1"}], "pagination": {"nextCursor": None, "prevCursor": None}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        result = list(paginate_pages(fetcher))
+        assert len(result) == 1
+
+    def test_empty_data(self):
+        pages_data = [
+            {"data": [], "pagination": {"nextCursor": None, "prevCursor": None}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        result = list(paginate_pages(fetcher))
+        assert len(result) == 1
+        assert result[0]["data"] == []
+
+    def test_error_propagation(self):
+        call_count = [0]
+
+        def fetcher(cursor=None):
+            idx = call_count[0]
+            call_count[0] += 1
+            if idx == 0:
+                return {"data": [{"id": "1"}], "pagination": {"nextCursor": "c2", "prevCursor": None}}
+            raise RuntimeError("API error")
+
+        with pytest.raises(RuntimeError, match="API error"):
+            list(paginate_pages(fetcher))
+
+
+class TestPaginate:
+    def test_yields_individual_items(self):
+        pages_data = [
+            {"data": [{"id": "1"}, {"id": "2"}], "pagination": {"nextCursor": "c2", "prevCursor": None}},
+            {"data": [{"id": "3"}], "pagination": {"nextCursor": None, "prevCursor": "c2"}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        items = list(paginate(fetcher))
+        assert items == [{"id": "1"}, {"id": "2"}, {"id": "3"}]
+
+    def test_respects_max_pages(self):
+        pages_data = [
+            {"data": [{"id": "1"}], "pagination": {"nextCursor": "c2", "prevCursor": None}},
+            {"data": [{"id": "2"}], "pagination": {"nextCursor": None, "prevCursor": "c2"}},
+        ]
+        fetcher = make_fetcher(pages_data)
+
+        items = list(paginate(fetcher, max_pages=1))
+        assert items == [{"id": "1"}]
+        assert fetcher.call_count[0] == 1