proxyrequest-sdk 1.0.0__tar.gz → 2.1.0__tar.gz

proxyrequest_sdk-2.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the ProxyRequest Python SDK are documented here.
+
+## Unreleased
+
+## 2.1.0 - 2026-09-17
+
+- Add atomic per-package data reset with typed requests, response metadata, and idempotent retries.
+- Refresh the public API contract and document root balances versus child allocations.
+
+## 2.0.0 - 2026-09-16
+
+- Replace the incorrect webhook verifier with the actual `X-Signature`
+  Base64 HMAC-SHA256 format over exact raw bytes.
+
+- Regenerated from the public backend contract (81 operations, 130 schemas),
+  excluding the two disabled sessions-management operations from generated clients.
+- Added the optional `pending`/`paid` status to invoice creation requests.
+- Added typed OTP verification and 200/202 login support for sync and async clients.
+- Corrected MFA bodies, payment fields, nullable invoices, and both backend user modes.
+- Preserved HTTP status, raw response, headers, cause, and idempotency key when
+  response decoding fails; HTTP errors are classified before model decoding.
+- Replaced fixed contract-size gates and added backend-serializer regression fixtures.
+
+- Added automatic and explicit idempotency keys with bounded ambiguous-outcome
+  retries.
+- Added response metadata variants and explicit ETag/`If-Match` optimistic
+  concurrency support.
+
+## 1.0.0 - 2026-08-21
+
+- Initial stable release covering all 82 public API operations.
+- Added synchronous and asynchronous clients with typed attrs models.
+- Added normalized errors, lazy pagination, invoice downloads, raw requests,
+  and signed webhook verification.
+- Added purchase and reseller provisioning guides.

{proxyrequest_sdk-1.0.0 → proxyrequest_sdk-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyrequest-sdk
-Version: 1.0.0
+Version: 2.1.0
 Summary: Official sync and async Python SDK for the ProxyRequest public API.
 Project-URL: Homepage, https://proxyrequest.com
 Project-URL: Documentation, https://proxyrequest.com/docs/
@@ -31,11 +31,11 @@ Description-Content-Type: text/markdown
 # ProxyRequest Python SDK
 
 [![CI](https://github.com/proxyrequest/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/proxyrequest/python-sdk/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/proxyrequest-sdk.svg)](https://pypi.org/project/proxyrequest-sdk/)
-[![Python](https://img.shields.io/pypi/pyversions/proxyrequest-sdk.svg)](https://pypi.org/project/proxyrequest-sdk/)
+[![PyPI](https://img.shields.io/pypi/v/proxyrequest-sdk.svg?cacheSeconds=300)](https://pypi.org/project/proxyrequest-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/proxyrequest-sdk.svg?cacheSeconds=300)](https://pypi.org/project/proxyrequest-sdk/)
 
 Official synchronous and asynchronous Python client for the
-[ProxyRequest](https://proxyrequest.com/) public API. It covers all 82 operations
+[ProxyRequest](https://proxyrequest.com/) public API. It covers 80 supported operations
 in the current contract: users, orders, proxy generation, analytics, invoices,
 packages, locations, webhooks, API keys, Telegram integration, and more.
 
@@ -150,7 +150,12 @@ async def list_users() -> None:
 
 ## Resource API
 
-`Client` and `AsyncClient` expose one object per API group:
+`Client` and `AsyncClient` expose 17 API groups. The pinned public schema contains
+82 operations; disabled `sessions_list` and `sessions_destroy` operations are
+intentionally excluded. Sticky session options in proxy generation remain supported.
+
+See [backend compatibility and MFA](docs/backend-compatibility.md) for updated
+login examples and response-model migration notes.
 
 ```python
 client.authorization
@@ -168,8 +173,6 @@ client.locations
 client.api_keys
 client.webhooks
 client.telegram
-client.telegram_service
-client.sessions
 client.settings
 client.news
 ```
@@ -182,6 +185,31 @@ opaque `str`), and all byte amounts are Python integers.
 See the generated [API resource reference](https://github.com/proxyrequest/python-sdk/blob/main/docs/reference/api.md)
 and [model reference](https://github.com/proxyrequest/python-sdk/blob/main/docs/reference/models.md).
 
+## Automatic retries and optimistic concurrency
+
+The SDK automatically protects supported writes during up to three total
+attempts after a network failure, or after `409 Conflict` with a numeric
+`Retry-After` of at most five seconds. Other HTTP errors are returned
+immediately. This protection applies inside one running call. If the process
+stops before saving the result, inspect the affected resource before submitting
+another write:
+
+```python
+response = client.users.create_with_response(
+    body=UserCreateRequest(username="customer-reference", password="secret"),
+)
+
+print(response.data.id, response.etag)
+```
+
+Every generated method has a `_with_response` variant exposing `status_code`,
+`headers`, and `etag`.
+
+Operations that declare `If-Match` accept the latest strong ETag. A stale value
+raises `ApiError` with `ErrorKind.PRECONDITION` and exposes the current server
+value as `current_etag`. ETags are explicit response metadata and are not cached
+by the SDK.
+
 ## Pagination
 
 List endpoints return their typed OpenAPI page. Use `paginate()` to follow all
@@ -218,9 +246,9 @@ except ApiError as error:
     print(error.status_code, error.request_id, error.field_errors)
 ```
 
-The SDK does not automatically retry writes or refresh JWTs. Call
-`client.authorization.refresh(...)` explicitly when your application owns a
-token pair.
+Supported writes receive bounded automatic retries for transient failures.
+JWTs are never refreshed automatically; call `client.authorization.refresh(...)`
+explicitly when your application owns a token pair.
 
 ## Configuration and custom deployments
 
@@ -252,21 +280,6 @@ print(path, download.content_type)
 
 `save()` does not overwrite an existing file unless `overwrite=True` is passed.
 
-## Telegram service operations
-
-Account-side Telegram operations use the client's API key. Bot service
-operations require the service secret explicitly and never reuse the ordinary
-Authorization header:
-
-```python
-from proxyrequest_sdk.models import TelegramSessionRequest
-
-session = client.telegram_service.create_session(
-    body=TelegramSessionRequest(telegram_user_id=123456789, chat_id=123456789),
-    service_secret=os.environ["PROXYREQUEST_TELEGRAM_SECRET"],
-)
-```
-
 ## Webhook verification
 
 Verify the exact raw body before decoding it:
@@ -276,12 +289,13 @@ from proxyrequest_sdk import WebhookVerifier
 
 payload = WebhookVerifier.decode_verified_json(
     raw_body,
-    request.headers.get("X-Webhook-Signature", ""),
+    request.headers.get("X-Signature", ""),
     os.environ["PROXYREQUEST_WEBHOOK_SECRET"],
-    timestamp_header=request.headers.get("X-Webhook-Timestamp"),
 )
 ```
 
+Deliveries use standard padded Base64 HMAC-SHA256 over the raw body, without a signed timestamp. Verification accepts only this current format. It authenticates the body, but does not prevent replay: deduplicate usage events in your application. These helpers require SDK 2.0.0 or newer; version 1.0.0 does not support the current delivery format.
+
 ## Platform documentation
 
 - [Platform documentation](https://proxyrequest.com/docs/): capabilities,
@@ -320,3 +334,21 @@ update it. Generation is pinned and CI rejects uncommitted contract changes.
 ## License
 
 MIT
+
+## Reset remaining data (SDK 2.1.0+)
+
+```python
+from proxyrequest_sdk.models import ResetDataRequest
+
+order = client.users.reset_data(
+    id=user_id,
+    body=ResetDataRequest(package_id=package_id),
+    idempotency_key=reset_operation_id,
+)
+```
+
+Send only `package_id`, without `data`. A system administrator can reset any user; other accounts can reset only their direct children. The server atomically clears positive, zero, or negative remaining data for a finite package and returns the updated order. Unlimited packages are rejected. Root orders lose their remaining ledger balances; child orders lose their remaining quota without changing the parent pool. Usage history and invoices are preserved.
+
+Persist one operation ID and reuse it when retrying the same reset, including after a process restart. This prevents a repeated request from clearing a later top-up. Use subtraction when an explicit amount should be removed from a child quota. The backend must support the reset endpoint before calling it.
+
+Version 2.1 retains legacy user and invoice models from 2.0 for compatibility with older deployments. These compatibility types do not change the current public API contract.

{proxyrequest_sdk-1.0.0 → proxyrequest_sdk-2.1.0}/README.md

@@ -1,11 +1,11 @@
 # ProxyRequest Python SDK
 
 [![CI](https://github.com/proxyrequest/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/proxyrequest/python-sdk/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/proxyrequest-sdk.svg)](https://pypi.org/project/proxyrequest-sdk/)
-[![Python](https://img.shields.io/pypi/pyversions/proxyrequest-sdk.svg)](https://pypi.org/project/proxyrequest-sdk/)
+[![PyPI](https://img.shields.io/pypi/v/proxyrequest-sdk.svg?cacheSeconds=300)](https://pypi.org/project/proxyrequest-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/proxyrequest-sdk.svg?cacheSeconds=300)](https://pypi.org/project/proxyrequest-sdk/)
 
 Official synchronous and asynchronous Python client for the
-[ProxyRequest](https://proxyrequest.com/) public API. It covers all 82 operations
+[ProxyRequest](https://proxyrequest.com/) public API. It covers 80 supported operations
 in the current contract: users, orders, proxy generation, analytics, invoices,
 packages, locations, webhooks, API keys, Telegram integration, and more.
 
@@ -120,7 +120,12 @@ async def list_users() -> None:
 
 ## Resource API
 
-`Client` and `AsyncClient` expose one object per API group:
+`Client` and `AsyncClient` expose 17 API groups. The pinned public schema contains
+82 operations; disabled `sessions_list` and `sessions_destroy` operations are
+intentionally excluded. Sticky session options in proxy generation remain supported.
+
+See [backend compatibility and MFA](docs/backend-compatibility.md) for updated
+login examples and response-model migration notes.
 
 ```python
 client.authorization
@@ -138,8 +143,6 @@ client.locations
 client.api_keys
 client.webhooks
 client.telegram
-client.telegram_service
-client.sessions
 client.settings
 client.news
 ```
@@ -152,6 +155,31 @@ opaque `str`), and all byte amounts are Python integers.
 See the generated [API resource reference](https://github.com/proxyrequest/python-sdk/blob/main/docs/reference/api.md)
 and [model reference](https://github.com/proxyrequest/python-sdk/blob/main/docs/reference/models.md).
 
+## Automatic retries and optimistic concurrency
+
+The SDK automatically protects supported writes during up to three total
+attempts after a network failure, or after `409 Conflict` with a numeric
+`Retry-After` of at most five seconds. Other HTTP errors are returned
+immediately. This protection applies inside one running call. If the process
+stops before saving the result, inspect the affected resource before submitting
+another write:
+
+```python
+response = client.users.create_with_response(
+    body=UserCreateRequest(username="customer-reference", password="secret"),
+)
+
+print(response.data.id, response.etag)
+```
+
+Every generated method has a `_with_response` variant exposing `status_code`,
+`headers`, and `etag`.
+
+Operations that declare `If-Match` accept the latest strong ETag. A stale value
+raises `ApiError` with `ErrorKind.PRECONDITION` and exposes the current server
+value as `current_etag`. ETags are explicit response metadata and are not cached
+by the SDK.
+
 ## Pagination
 
 List endpoints return their typed OpenAPI page. Use `paginate()` to follow all
@@ -188,9 +216,9 @@ except ApiError as error:
     print(error.status_code, error.request_id, error.field_errors)
 ```
 
-The SDK does not automatically retry writes or refresh JWTs. Call
-`client.authorization.refresh(...)` explicitly when your application owns a
-token pair.
+Supported writes receive bounded automatic retries for transient failures.
+JWTs are never refreshed automatically; call `client.authorization.refresh(...)`
+explicitly when your application owns a token pair.
 
 ## Configuration and custom deployments
 
@@ -222,21 +250,6 @@ print(path, download.content_type)
 
 `save()` does not overwrite an existing file unless `overwrite=True` is passed.
 
-## Telegram service operations
-
-Account-side Telegram operations use the client's API key. Bot service
-operations require the service secret explicitly and never reuse the ordinary
-Authorization header:
-
-```python
-from proxyrequest_sdk.models import TelegramSessionRequest
-
-session = client.telegram_service.create_session(
-    body=TelegramSessionRequest(telegram_user_id=123456789, chat_id=123456789),
-    service_secret=os.environ["PROXYREQUEST_TELEGRAM_SECRET"],
-)
-```
-
 ## Webhook verification
 
 Verify the exact raw body before decoding it:
@@ -246,12 +259,13 @@ from proxyrequest_sdk import WebhookVerifier
 
 payload = WebhookVerifier.decode_verified_json(
     raw_body,
-    request.headers.get("X-Webhook-Signature", ""),
+    request.headers.get("X-Signature", ""),
     os.environ["PROXYREQUEST_WEBHOOK_SECRET"],
-    timestamp_header=request.headers.get("X-Webhook-Timestamp"),
 )
 ```
 
+Deliveries use standard padded Base64 HMAC-SHA256 over the raw body, without a signed timestamp. Verification accepts only this current format. It authenticates the body, but does not prevent replay: deduplicate usage events in your application. These helpers require SDK 2.0.0 or newer; version 1.0.0 does not support the current delivery format.
+
 ## Platform documentation
 
 - [Platform documentation](https://proxyrequest.com/docs/): capabilities,
@@ -290,3 +304,21 @@ update it. Generation is pinned and CI rejects uncommitted contract changes.
 ## License
 
 MIT
+
+## Reset remaining data (SDK 2.1.0+)
+
+```python
+from proxyrequest_sdk.models import ResetDataRequest
+
+order = client.users.reset_data(
+    id=user_id,
+    body=ResetDataRequest(package_id=package_id),
+    idempotency_key=reset_operation_id,
+)
+```
+
+Send only `package_id`, without `data`. A system administrator can reset any user; other accounts can reset only their direct children. The server atomically clears positive, zero, or negative remaining data for a finite package and returns the updated order. Unlimited packages are rejected. Root orders lose their remaining ledger balances; child orders lose their remaining quota without changing the parent pool. Usage history and invoices are preserved.
+
+Persist one operation ID and reuse it when retrying the same reset, including after a process restart. This prevents a repeated request from clearing a later top-up. Use subtraction when an explicit amount should be removed from a child quota. The backend must support the reset endpoint before calling it.
+
+Version 2.1 retains legacy user and invoice models from 2.0 for compatibility with older deployments. These compatibility types do not change the current public API contract.