python-zendesk-sdk 0.12.0__tar.gz → 0.13.0__tar.gz

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/.gitignore

@@ -190,4 +190,5 @@ debug_*.py
 
 # Local directories
 .claude/
-llm/
+llm/
+CLAUDE.md

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.12.0
+Version: 0.13.0
 Summary: Modern Python SDK for Zendesk API
 Project-URL: Homepage, https://github.com/bormog/python-zendesk-sdk
 Project-URL: Repository, https://github.com/bormog/python-zendesk-sdk
@@ -68,6 +68,7 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Search](#search)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
+- [Proactive Rate Limiting](#proactive-rate-limiting)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -102,6 +103,8 @@ Zendesk has a powerful REST API, but using it directly is painful:
 - **Caching**: TTL-based caching for users, organizations, and Help Center
 - **Help Center**: Full CRUD for Categories, Sections, and Articles
 - **Async HTTP**: Built on httpx with retry logic, rate limiting, exponential backoff
+- **Proactive Rate Limiting**: Monitors `X-Rate-Limit-Remaining` and throttles before hitting limits
+- **Authentication**: Token auth (Basic Auth) and OAuth (Bearer token)
 - **Configuration**: Environment variables or direct instantiation
 
 ## Installation
@@ -141,20 +144,33 @@ asyncio.run(main())
 
 ## Configuration
 
-### Direct instantiation
+### Token Authentication
 ```python
 config = ZendeskConfig(
     subdomain="mycompany",
     email="user@example.com",
-    token="api_token_here"
+    token="api_token_here",
+)
+```
+
+### OAuth Authentication
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    oauth_token="your_oauth_token",
 )
 ```
 
 ### Environment variables
 ```bash
+# Token auth
 export ZENDESK_SUBDOMAIN=mycompany
 export ZENDESK_EMAIL=user@example.com
 export ZENDESK_TOKEN=api_token_here
+
+# Or OAuth
+export ZENDESK_SUBDOMAIN=mycompany
+export ZENDESK_OAUTH_TOKEN=your_oauth_token
 ```
 
 ```python
@@ -656,6 +672,29 @@ config = ZendeskConfig(
 )
 ```
 
+### Proactive Rate Limiting
+
+By default, the SDK reacts to rate limiting after hitting a 429 response. With proactive rate limiting, the SDK reads the `X-Rate-Limit-Remaining` header from every response and starts throttling **before** hitting the limit:
+
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    proactive_ratelimit=50,                     # Start throttling when < 50 requests remaining
+    proactive_ratelimit_request_interval=10,    # Wait 10s between requests when throttling
+)
+```
+
+When `X-Rate-Limit-Remaining` drops below the threshold, the SDK pauses between requests to let the quota recover. Once remaining goes back above the threshold, requests resume at full speed.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proactive_ratelimit` | None (disabled) | Threshold to start throttling |
+| `proactive_ratelimit_request_interval` | 10 | Seconds to wait between requests when throttling |
+
+Zendesk typically allows 400 requests per minute. A threshold of 40-60 provides a good safety margin.
+
 ## Caching
 
 The SDK includes built-in caching for frequently accessed resources. Caching is enabled by default and can be configured or disabled.

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/README.md

@@ -30,6 +30,7 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Search](#search)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
+- [Proactive Rate Limiting](#proactive-rate-limiting)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -64,6 +65,8 @@ Zendesk has a powerful REST API, but using it directly is painful:
 - **Caching**: TTL-based caching for users, organizations, and Help Center
 - **Help Center**: Full CRUD for Categories, Sections, and Articles
 - **Async HTTP**: Built on httpx with retry logic, rate limiting, exponential backoff
+- **Proactive Rate Limiting**: Monitors `X-Rate-Limit-Remaining` and throttles before hitting limits
+- **Authentication**: Token auth (Basic Auth) and OAuth (Bearer token)
 - **Configuration**: Environment variables or direct instantiation
 
 ## Installation
@@ -103,20 +106,33 @@ asyncio.run(main())
 
 ## Configuration
 
-### Direct instantiation
+### Token Authentication
 ```python
 config = ZendeskConfig(
     subdomain="mycompany",
     email="user@example.com",
-    token="api_token_here"
+    token="api_token_here",
+)
+```
+
+### OAuth Authentication
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    oauth_token="your_oauth_token",
 )
 ```
 
 ### Environment variables
 ```bash
+# Token auth
 export ZENDESK_SUBDOMAIN=mycompany
 export ZENDESK_EMAIL=user@example.com
 export ZENDESK_TOKEN=api_token_here
+
+# Or OAuth
+export ZENDESK_SUBDOMAIN=mycompany
+export ZENDESK_OAUTH_TOKEN=your_oauth_token
 ```
 
 ```python
@@ -618,6 +634,29 @@ config = ZendeskConfig(
 )
 ```
 
+### Proactive Rate Limiting
+
+By default, the SDK reacts to rate limiting after hitting a 429 response. With proactive rate limiting, the SDK reads the `X-Rate-Limit-Remaining` header from every response and starts throttling **before** hitting the limit:
+
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    proactive_ratelimit=50,                     # Start throttling when < 50 requests remaining
+    proactive_ratelimit_request_interval=10,    # Wait 10s between requests when throttling
+)
+```
+
+When `X-Rate-Limit-Remaining` drops below the threshold, the SDK pauses between requests to let the quota recover. Once remaining goes back above the threshold, requests resume at full speed.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proactive_ratelimit` | None (disabled) | Threshold to start throttling |
+| `proactive_ratelimit_request_interval` | 10 | Seconds to wait between requests when throttling |
+
+Zendesk typically allows 400 requests per minute. A threshold of 40-60 provides a good safety margin.
+
 ## Caching
 
 The SDK includes built-in caching for frequently accessed resources. Caching is enabled by default and can be configured or disabled.

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-zendesk-sdk"
-version = "0.12.0"
+version = "0.13.0"
 description = "Modern Python SDK for Zendesk API"
 authors = [
     {name = "bormog"}

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/__init__.py

@@ -5,7 +5,7 @@ This package provides a clean, async-first interface to the Zendesk API
 with full type safety and comprehensive error handling.
 """
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 
 from .client import ZendeskClient
 from .clients import (

python_zendesk_sdk-0.13.0/src/zendesk_sdk/config.py

@@ -0,0 +1,175 @@
+"""Configuration management for Zendesk SDK."""
+
+import os
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, computed_field, field_validator, model_validator
+
+
+class CacheConfig(BaseModel):
+    """Cache configuration for Zendesk SDK.
+
+    Controls TTL (time-to-live) and max size for different resource caches.
+    Set enabled=False to disable caching entirely.
+    """
+
+    enabled: bool = Field(default=True, description="Enable/disable caching")
+
+    # Users cache
+    user_ttl: int = Field(default=300, description="User cache TTL in seconds (default: 5 min)", ge=0)
+    user_maxsize: int = Field(default=1000, description="Max cached users", ge=1)
+
+    # Organizations cache
+    org_ttl: int = Field(default=600, description="Organization cache TTL in seconds (default: 10 min)", ge=0)
+    org_maxsize: int = Field(default=500, description="Max cached organizations", ge=1)
+
+    # Groups cache
+    group_ttl: int = Field(default=600, description="Group cache TTL in seconds (default: 10 min)", ge=0)
+    group_maxsize: int = Field(default=500, description="Max cached groups", ge=1)
+
+    # Help Center cache
+    article_ttl: int = Field(default=900, description="Article cache TTL in seconds (default: 15 min)", ge=0)
+    article_maxsize: int = Field(default=500, description="Max cached articles", ge=1)
+
+    category_ttl: int = Field(default=1800, description="Category cache TTL in seconds (default: 30 min)", ge=0)
+    category_maxsize: int = Field(default=200, description="Max cached categories", ge=1)
+
+    section_ttl: int = Field(default=1800, description="Section cache TTL in seconds (default: 30 min)", ge=0)
+    section_maxsize: int = Field(default=200, description="Max cached sections", ge=1)
+
+
+class ZendeskConfig(BaseModel):
+    """Configuration for Zendesk API client.
+
+    Supports two authentication methods (mutually exclusive):
+    - Token auth: email + token (Basic Auth)
+    - OAuth: oauth_token (Bearer token)
+
+    Environment variables: ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN, ZENDESK_OAUTH_TOKEN.
+    """
+
+    subdomain: str = Field(
+        ...,
+        description="Zendesk subdomain (e.g., 'mycompany' for mycompany.zendesk.com)",
+        min_length=1,
+    )
+    email: Optional[str] = Field(
+        default=None,
+        description="User email for token authentication",
+    )
+    token: Optional[str] = Field(
+        default=None,
+        description="API token for token authentication",
+    )
+    oauth_token: Optional[str] = Field(
+        default=None,
+        description="OAuth token for Bearer authentication",
+    )
+    timeout: float = Field(
+        default=30.0,
+        description="HTTP request timeout in seconds",
+        gt=0,
+    )
+    max_retries: int = Field(
+        default=3,
+        description="Maximum number of retry attempts",
+        ge=0,
+    )
+    proactive_ratelimit: Optional[int] = Field(
+        default=None,
+        description="Start sleeping when X-Rate-Limit-Remaining drops below this threshold",
+        ge=1,
+    )
+    proactive_ratelimit_request_interval: int = Field(
+        default=10,
+        description="Seconds to wait between requests when proactive rate limit threshold is reached",
+        ge=1,
+    )
+    cache: CacheConfig = Field(
+        default_factory=CacheConfig,
+        description="Cache configuration",
+    )
+
+    def __init__(self, **data: Any) -> None:
+        # Load from environment variables if not provided
+        if "subdomain" not in data:
+            data["subdomain"] = os.getenv("ZENDESK_SUBDOMAIN", data.get("subdomain"))
+
+        # Only load env vars for one auth method — explicit args take precedence
+        has_explicit_token_auth = "email" in data or "token" in data
+        has_explicit_oauth = "oauth_token" in data
+
+        if not has_explicit_token_auth and not has_explicit_oauth:
+            # Nothing explicit — try env vars, token auth first
+            env_email = os.getenv("ZENDESK_EMAIL")
+            env_token = os.getenv("ZENDESK_TOKEN")
+            env_oauth = os.getenv("ZENDESK_OAUTH_TOKEN")
+            if env_email or env_token:
+                data.setdefault("email", env_email)
+                data.setdefault("token", env_token)
+            elif env_oauth:
+                data.setdefault("oauth_token", env_oauth)
+        elif has_explicit_token_auth and not has_explicit_oauth:
+            # Token auth explicit — fill missing from env
+            data.setdefault("email", os.getenv("ZENDESK_EMAIL"))
+            data.setdefault("token", os.getenv("ZENDESK_TOKEN"))
+        elif has_explicit_oauth and not has_explicit_token_auth:
+            # OAuth explicit — only fill oauth from env
+            data.setdefault("oauth_token", os.getenv("ZENDESK_OAUTH_TOKEN"))
+
+        super().__init__(**data)
+
+    @model_validator(mode="after")
+    def validate_auth(self) -> "ZendeskConfig":
+        """Validate that exactly one auth method is provided."""
+        has_token_auth = self.email is not None or self.token is not None
+        has_oauth = self.oauth_token is not None
+
+        if has_token_auth and has_oauth:
+            raise ValueError("Cannot use both token auth (email/token) and oauth_token simultaneously")
+
+        if not has_token_auth and not has_oauth:
+            raise ValueError("Either email/token or oauth_token must be provided")
+
+        if has_token_auth:
+            if not self.email or not self.token:
+                raise ValueError("Both email and token are required for token authentication")
+            if "@" not in self.email:
+                raise ValueError("Invalid email format")
+
+        return self
+
+    @field_validator("subdomain")
+    @classmethod
+    def validate_subdomain(cls, v: str) -> str:
+        """Validate subdomain format."""
+        if not v.replace("-", "").replace("_", "").isalnum():
+            raise ValueError("Subdomain can only contain letters, numbers, hyphens and underscores")
+        return v.lower()
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def endpoint(self) -> str:
+        """Generate the base API endpoint URL."""
+        return f"https://{self.subdomain}.zendesk.com/api/v2"
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def auth_tuple(self) -> Optional[tuple[str, str]]:
+        """Generate authentication tuple for HTTP requests. None for OAuth mode."""
+        if self.email and self.token:
+            return f"{self.email}/token", self.token
+        return None
+
+    def __repr__(self) -> str:
+        """String representation without exposing credentials."""
+        auth_info = f"email='{self.email}'" if self.email else "oauth=True"
+        parts = [
+            f"subdomain='{self.subdomain}'",
+            auth_info,
+            f"timeout={self.timeout}",
+            f"max_retries={self.max_retries}",
+        ]
+        if self.proactive_ratelimit is not None:
+            parts.append(f"proactive_ratelimit={self.proactive_ratelimit}")
+        return f"ZendeskConfig({', '.join(parts)})"

{python_zendesk_sdk-0.12.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/http_client.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+from time import monotonic
 from typing import Any, Dict, Optional
 from urllib.parse import urljoin
 
@@ -31,6 +32,10 @@ class HTTPClient:
         self._client: Optional[httpx.AsyncClient] = None
         self._closed = False
 
+        # Proactive rate limit tracking
+        self._last_call_time: Optional[float] = None
+        self._last_limit_remaining: Optional[int] = None
+
     @property
     def client(self) -> httpx.AsyncClient:
         """Get or create httpx async client."""
@@ -40,14 +45,18 @@ class HTTPClient:
 
     def _create_client(self) -> httpx.AsyncClient:
         """Create configured httpx async client."""
-        auth = httpx.BasicAuth(username=self.config.auth_tuple[0], password=self.config.auth_tuple[1])
-
         headers = {
             "User-Agent": "python-zendesk-sdk/0.1.0",
             "Content-Type": "application/json",
             "Accept": "application/json",
         }
 
+        auth: Optional[httpx.BasicAuth] = None
+        if self.config.auth_tuple:
+            auth = httpx.BasicAuth(username=self.config.auth_tuple[0], password=self.config.auth_tuple[1])
+        elif self.config.oauth_token:
+            headers["Authorization"] = f"Bearer {self.config.oauth_token}"
+
         return httpx.AsyncClient(
             auth=auth,
             headers=headers,
@@ -55,6 +64,40 @@ class HTTPClient:
             limits=httpx.Limits(max_keepalive_connections=10, max_connections=20),
         )
 
+    async def _apply_proactive_ratelimit(self) -> None:
+        """Apply proactive rate limiting by sleeping if remaining requests are below threshold."""
+        if self.config.proactive_ratelimit is None:
+            return
+        if self._last_limit_remaining is None or self._last_call_time is None:
+            return
+
+        if self._last_limit_remaining >= self.config.proactive_ratelimit:  # type: ignore[operator]
+            return
+
+        time_since_last = monotonic() - self._last_call_time
+        interval = self.config.proactive_ratelimit_request_interval
+        if time_since_last >= interval:
+            return
+
+        remaining_sleep = interval - time_since_last
+        logger.warning(
+            f"Proactive rate limit: {self._last_limit_remaining} remaining "
+            f"(threshold: {self.config.proactive_ratelimit}), sleeping {remaining_sleep:.1f}s"
+        )
+        await asyncio.sleep(remaining_sleep)
+
+    def _update_rate_limit_state(self, response: httpx.Response) -> None:
+        """Update rate limit tracking state from response headers."""
+        if self.config.proactive_ratelimit is None:
+            return
+        self._last_call_time = monotonic()
+        remaining_header = response.headers.get("X-Rate-Limit-Remaining")
+        if remaining_header is not None:
+            try:
+                self._last_limit_remaining = int(remaining_header)
+            except (ValueError, TypeError):
+                pass
+
     async def _make_request_with_retry(
         self,
         method: str,
@@ -72,6 +115,9 @@ class HTTPClient:
 
         for attempt in range(max_retries + 1):
             try:
+                # Apply proactive rate limiting before request
+                await self._apply_proactive_ratelimit()
+
                 # Make the actual request
                 response = await self.client.request(
                     method=method,
@@ -80,6 +126,9 @@ class HTTPClient:
                     json=json,
                 )
 
+                # Update rate limit tracking state
+                self._update_rate_limit_state(response)
+
                 # Handle different response types
                 retry_info = await self._handle_response(response, attempt, max_retries)
                 if retry_info:

python_zendesk_sdk-0.13.0/tests/test_config.py

@@ -0,0 +1,216 @@
+"""Tests for ZendeskConfig."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+from pydantic import ValidationError
+
+from zendesk_sdk.config import ZendeskConfig
+
+
+class TestZendeskConfig:
+    """Test cases for ZendeskConfig class."""
+
+    def test_basic_config_with_token(self):
+        """Test creating config with email/token authentication."""
+        config = ZendeskConfig(
+            subdomain="test",
+            email="user@example.com",
+            token="api_token_123",
+        )
+
+        assert config.subdomain == "test"
+        assert config.email == "user@example.com"
+        assert config.token == "api_token_123"
+        assert config.oauth_token is None
+        assert config.endpoint == "https://test.zendesk.com/api/v2"
+        assert config.auth_tuple == ("user@example.com/token", "api_token_123")
+
+    def test_basic_config_with_oauth_token(self):
+        """Test creating config with OAuth token authentication."""
+        config = ZendeskConfig(
+            subdomain="test",
+            oauth_token="oauth_token_123",
+        )
+
+        assert config.subdomain == "test"
+        assert config.oauth_token == "oauth_token_123"
+        assert config.email is None
+        assert config.token is None
+        assert config.auth_tuple is None
+        assert config.endpoint == "https://test.zendesk.com/api/v2"
+
+    def test_invalid_timeout(self):
+        """Test invalid timeout values."""
+        with pytest.raises(ValidationError):
+            ZendeskConfig(
+                subdomain="test",
+                email="user@example.com",
+                token="api_token_123",
+                timeout=0.0,  # Must be > 0
+            )
+
+    def test_invalid_max_retries(self):
+        """Test invalid max_retries values."""
+        with pytest.raises(ValidationError):
+            ZendeskConfig(
+                subdomain="test",
+                email="user@example.com",
+                token="api_token_123",
+                max_retries=-1,  # Must be >= 0
+            )
+
+    def test_missing_all_auth(self):
+        """Test that at least one auth method is required."""
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(ValidationError, match="Either email/token or oauth_token must be provided"):
+                ZendeskConfig(subdomain="test")
+
+    def test_both_auth_methods(self):
+        """Test that token and oauth_token are mutually exclusive."""
+        with pytest.raises(ValidationError, match="Cannot use both"):
+            ZendeskConfig(
+                subdomain="test",
+                email="user@example.com",
+                token="api_token_123",
+                oauth_token="oauth_token_123",
+            )
+
+    def test_email_without_token(self):
+        """Test that email requires token."""
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(ValidationError, match="Both email and token are required"):
+                ZendeskConfig(
+                    subdomain="test",
+                    email="user@example.com",
+                )
+
+    def test_token_without_email(self):
+        """Test that token requires email."""
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(ValidationError, match="Both email and token are required"):
+                ZendeskConfig(
+                    subdomain="test",
+                    token="api_token_123",
+                )
+
+    def test_invalid_email(self):
+        """Test invalid email format."""
+        with pytest.raises(ValidationError, match="Invalid email format"):
+            ZendeskConfig(
+                subdomain="test",
+                email="invalid-email",
+                token="api_token_123",
+            )
+
+    def test_env_variables_token_auth(self):
+        """Test loading token auth config from environment variables."""
+        with patch.dict(
+            os.environ,
+            {
+                "ZENDESK_SUBDOMAIN": "env-test",
+                "ZENDESK_EMAIL": "env@example.com",
+                "ZENDESK_TOKEN": "env_token_123",
+            },
+        ):
+            config = ZendeskConfig()
+            assert config.subdomain == "env-test"
+            assert config.email == "env@example.com"
+            assert config.token == "env_token_123"
+
+    def test_env_variables_oauth(self):
+        """Test loading OAuth config from environment variables."""
+        with patch.dict(
+            os.environ,
+            {
+                "ZENDESK_SUBDOMAIN": "env-test",
+                "ZENDESK_OAUTH_TOKEN": "env_oauth_123",
+            },
+            clear=True,
+        ):
+            config = ZendeskConfig()
+            assert config.subdomain == "env-test"
+            assert config.oauth_token == "env_oauth_123"
+            assert config.auth_tuple is None
+
+    def test_repr_hides_token(self):
+        """Test that repr doesn't expose token."""
+        config = ZendeskConfig(
+            subdomain="test",
+            email="user@example.com",
+            token="secret_token",
+        )
+        repr_str = repr(config)
+        assert "secret_token" not in repr_str
+        assert "test" in repr_str
+        assert "user@example.com" in repr_str
+
+    def test_repr_hides_oauth_token(self):
+        """Test that repr doesn't expose oauth_token."""
+        config = ZendeskConfig(
+            subdomain="test",
+            oauth_token="secret_oauth_token",
+        )
+        repr_str = repr(config)
+        assert "secret_oauth_token" not in repr_str
+        assert "oauth=True" in repr_str
+
+
+class TestRateLimitConfig:
+    """Test cases for proactive rate limiting configuration."""
+
+    def test_default_ratelimit_config(self):
+        """Test default values for rate limiting fields."""
+        config = ZendeskConfig(subdomain="test", email="user@example.com", token="abc123")
+        assert config.proactive_ratelimit is None
+        assert config.proactive_ratelimit_request_interval == 10
+
+    def test_proactive_ratelimit(self):
+        """Test setting proactive_ratelimit threshold."""
+        config = ZendeskConfig(subdomain="test", email="user@example.com", token="abc123", proactive_ratelimit=50)
+        assert config.proactive_ratelimit == 50
+
+    def test_proactive_ratelimit_with_custom_interval(self):
+        """Test setting proactive_ratelimit with custom interval."""
+        config = ZendeskConfig(
+            subdomain="test",
+            email="user@example.com",
+            token="abc123",
+            proactive_ratelimit=100,
+            proactive_ratelimit_request_interval=15,
+        )
+        assert config.proactive_ratelimit == 100
+        assert config.proactive_ratelimit_request_interval == 15
+
+    def test_proactive_ratelimit_invalid_zero(self):
+        """Test that proactive_ratelimit=0 raises ValidationError."""
+        with pytest.raises(ValidationError):
+            ZendeskConfig(subdomain="test", email="user@example.com", token="abc123", proactive_ratelimit=0)
+
+    def test_proactive_ratelimit_invalid_negative(self):
+        """Test that proactive_ratelimit=-1 raises ValidationError."""
+        with pytest.raises(ValidationError):
+            ZendeskConfig(subdomain="test", email="user@example.com", token="abc123", proactive_ratelimit=-1)
+
+    def test_proactive_ratelimit_interval_invalid_zero(self):
+        """Test that proactive_ratelimit_request_interval=0 raises ValidationError."""
+        with pytest.raises(ValidationError):
+            ZendeskConfig(
+                subdomain="test",
+                email="user@example.com",
+                token="abc123",
+                proactive_ratelimit_request_interval=0,
+            )
+
+    def test_repr_includes_proactive_ratelimit(self):
+        """Test that repr shows proactive_ratelimit when set."""
+        config = ZendeskConfig(subdomain="test", email="user@example.com", token="abc123", proactive_ratelimit=50)
+        repr_str = repr(config)
+        assert "proactive_ratelimit=50" in repr_str
+
+    def test_repr_excludes_proactive_ratelimit_when_none(self):
+        """Test that repr omits proactive_ratelimit when None."""
+        config = ZendeskConfig(subdomain="test", email="user@example.com", token="abc123")
+        repr_str = repr(config)
+        assert "proactive_ratelimit" not in repr_str