proxyrequest-sdk 2.0.0__tar.gz → 2.2.0__tar.gz

{proxyrequest_sdk-2.0.0 → proxyrequest_sdk-2.2.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the ProxyRequest Python SDK are documented here.
 
 ## Unreleased
 
+## 2.2.0 - 2026-09-21
+
+- Synchronize the public OpenAPI contract from backend commit `2c4505a`.
+- Accept Unix seconds and all documented date strings while preserving existing date inputs.
+- Keep the legacy logs hostname argument and existing response contracts.
+- Cover feed/domains pagination, nullable feed timestamps, and UInt64 IDs with regression tests.
+
+## 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`

{proxyrequest_sdk-2.0.0 → proxyrequest_sdk-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyrequest-sdk
-Version: 2.0.0
+Version: 2.2.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/
@@ -35,10 +35,13 @@ Description-Content-Type: text/markdown
 [![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 79 supported 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.
 
+See [analytics formats and compatibility](docs/analytics.md) for Unix timestamps,
+reporting windows, and feed identifiers.
+
 ## What is ProxyRequest?
 
 ProxyRequest is a white-label proxy platform for operators and resellers that
@@ -151,7 +154,7 @@ async def list_users() -> None:
 ## Resource API
 
 `Client` and `AsyncClient` expose 17 API groups. The pinned public schema contains
-81 operations; disabled `sessions_list` and `sessions_destroy` operations are
+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
@@ -334,3 +337,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-2.0.0 → proxyrequest_sdk-2.2.0}/README.md

@@ -5,10 +5,13 @@
 [![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 79 supported 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.
 
+See [analytics formats and compatibility](docs/analytics.md) for Unix timestamps,
+reporting windows, and feed identifiers.
+
 ## What is ProxyRequest?
 
 ProxyRequest is a white-label proxy platform for operators and resellers that
@@ -121,7 +124,7 @@ async def list_users() -> None:
 ## Resource API
 
 `Client` and `AsyncClient` expose 17 API groups. The pinned public schema contains
-81 operations; disabled `sessions_list` and `sessions_destroy` operations are
+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
@@ -304,3 +307,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-2.2.0/docs/analytics.md

@@ -0,0 +1,40 @@
+# Analytics compatibility
+
+The SDK accepts all documented reporting-window formats for `start` and `end`:
+ISO 8601 with or without an offset, `YYYY-MM-DD HH:MM:SS`, `DD-MM-YYYY HH:MM:SS`,
+`YYYY-MM-DD`, `DD-MM-YYYY`, and Unix timestamps in **seconds**, including fractions.
+Strings pass through unchanged; numeric timestamps are also accepted. Milliseconds
+are not converted automatically. Omitted parameters retain the server defaults.
+
+The server interprets offset-free date strings in the requested timezone, converts
+explicit offsets, and truncates reporting boundaries to the minute. Date-only
+values start at midnight. Missing, empty or unknown timezone names use the server's
+deployment timezone (UTC by default). Prefer explicit ISO offsets when timezone
+interpretation matters. Response date fields keep their existing types.
+
+The `hostname` filter on feed and domains accepts a comma-separated mixture of
+domains, IPv4/IPv6 addresses and HTTP(S) URLs. Normalization belongs to the server;
+the SDK preserves the supplied string. Bracket IPv6 addresses when adding a port.
+`include_sub_users` is a boolean on domains and overall. The legacy logs `hostname`
+argument remains available for source compatibility, but the server ignores it.
+
+Domain records contain `hostname`, `requests` and `data`; the SDK does not add a
+`timestamp` or a page `count`. Feed timestamps can legitimately be null.
+
+## Feed identifiers
+
+`FeedRecord.id` remains an arbitrary-precision Python `int`, preserving the full
+UInt64 range. Version 2.2 does not change response types, including datetime fields.
+Regression fixtures cover the reported feed IDs and numeric boundaries.
+
+```python
+page = client.analytics.list_feed(
+    start=1782864000.5,
+    end="2026-07-02T00:00:00Z",
+    timezone="Europe/Kiev",
+)
+id_value: int = page.results[0].id
+```
+
+Existing `datetime` inputs still serialize through `isoformat()`. All date formats
+are supported by sync and async clients, including methods with response metadata.

{proxyrequest_sdk-2.0.0 → proxyrequest_sdk-2.2.0}/docs/backend-compatibility.md

@@ -78,3 +78,41 @@ reauthenticate explicitly rather than retrying security mutations automatically.
 The compatibility suite covers sync/async clients with real serializer fixtures,
 OTP challenges, nullable and variable responses, and decoding/HTTP failures. No
 production mutations are used. See [audit and resolution status](SDK-AUDIT.md).
+
+## Analytics decoding diagnostics
+
+`analytics.list_feed()` returns `FeedResponse` with `count`, `next`, `previous`,
+`timezone`, `start`, `end`, and `results`. `analytics.list_domains()` returns
+`DomainsResponse` without a total `count`. Feed records support empty identifier
+strings and a null `timestamp`. Both endpoints use `limit`/`offset`; an integration
+that exposes `page`/`page_size` should translate them to
+`limit=page_size, offset=(page-1)*page_size`.
+
+`Unable to decode the ProxyRequest HTTP 200 response.` means that the SDK received
+HTTP 200 but could not parse the JSON or construct the response model. The message
+alone does not identify the cause. Capture the original exception and request ID:
+
+```python
+from importlib.metadata import version
+
+from proxyrequest_sdk import ApiError
+
+try:
+    page = client.analytics.list_feed(limit=20, offset=0)
+except ApiError as error:
+    print("SDK:", version("proxyrequest-sdk"))
+    print("HTTP:", error.status_code, "request:", error.request_id)
+    print("Decoder:", repr(error.__cause__))
+    raise
+```
+
+For example, a missing required field produces `KeyError('field_name')`;
+non-JSON response content produces `JSONDecodeError`. `error.raw_body` contains
+the original bytes for local inspection. Redact customer data before sharing it.
+The same diagnostics apply to `AsyncClient` and `*_with_response` calls.
+
+The analytics regression fixtures were rendered by the backend with synthetic
+ClickHouse rows; see [fixture provenance](../tests/fixtures/analytics-responses.md).
+They cover empty pages, nullable timestamps, timezone offsets, pagination without
+a total count, and the reported `Europe/Kiev` date window. Passing these tests does
+not establish the shape of a particular deployed server's response.

{proxyrequest_sdk-2.0.0 → proxyrequest_sdk-2.2.0}/docs/reference/api.md

@@ -153,6 +153,7 @@ All methods exist on both `Client` and `AsyncClient`; async calls must be awaite
 | `get()` | `GET /users/{id}` | `User` |
 | `list()` | `GET /users` | `PaginatedUserList` |
 | `list_orders()` | `GET /users/{id}/orders` | `PaginatedOrderList` |
+| `reset_data()` | `POST /users/{id}/data/reset` | `Order` |
 | `reset_password()` | `POST /users/{id}/password` | `User` |
 | `subtract_data()` | `POST /users/{id}/data/subtract` | `Order` |
 | `update()` | `PATCH /users/{id}` | `User` |

{proxyrequest_sdk-2.0.0 → proxyrequest_sdk-2.2.0}/docs/reference/models.md

@@ -102,6 +102,7 @@ Models use snake_case attributes and provide `to_dict()` / `from_dict()` helpers
 - `ProxyTypeEnum` — * `static` - Static * `residential` - Residential
 - `RecoverPasswordRequest` — Password recovery with enhanced security and comprehensive error handling.
 - `Region`
+- `ResetDataRequest`
 - `ResetPasswordRequest`
 - `Reward`
 - `RewardClaimRequestRequest`

proxyrequest_sdk-2.2.0/openapi/compatibility.json

@@ -0,0 +1,441 @@
+{
+  "description": "SDK 2.0 response compatibility only. The canonical public schema remains unchanged.",
+  "schemas": {
+    "InvoiceShort": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "maxLength": 36
+        },
+        "coupon": {
+          "allOf": [
+            {
+              "$ref": "#/components/schemas/Coupon"
+            }
+          ],
+          "readOnly": true,
+          "nullable": true
+        },
+        "country": {
+          "allOf": [
+            {
+              "$ref": "#/components/schemas/Country"
+            }
+          ],
+          "readOnly": true,
+          "nullable": true
+        },
+        "updated": {
+          "type": "string",
+          "format": "date-time",
+          "readOnly": true
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time",
+          "readOnly": true
+        },
+        "is_one_time": {
+          "type": "boolean",
+          "title": "One-Time Purchase",
+          "description": "Indicates whether this invoice is for a one-time purchase. Default is False, meaning it is a recurring invoice."
+        },
+        "is_payout": {
+          "type": "boolean",
+          "title": "Payout",
+          "description": "Indicates whether this invoice is a payout to the marketer. Default is False."
+        },
+        "internal_id": {
+          "type": "string",
+          "description": "A unique identifier for the invoice, generated automatically.",
+          "maxLength": 25
+        },
+        "status": {
+          "allOf": [
+            {
+              "$ref": "#/components/schemas/InvoiceStatusEnum"
+            }
+          ],
+          "description": "After changing invoice status to PAID, the invoice will be processed and user package created in case none exists. If you need to cancel the invoice, make sure to subtract data from the user package after changing the invoice status. Changing the status from PAID to any other will not affect the user package's data or proxies. * `pending` - Pending * `paid` - Paid * `unpaid` - Unpaid * `error` - Error"
+        },
+        "description": {
+          "type": "string",
+          "description": "A description of the invoice. This field is optional and can be left blank."
+        },
+        "connection_limit": {
+          "type": "integer",
+          "maximum": 2147483647,
+          "minimum": -1,
+          "description": "The maximum number of concurrent connections allowed for this package."
+        },
+        "data": {
+          "type": "integer",
+          "maximum": 1000000000000000,
+          "minimum": 0,
+          "format": "int64",
+          "title": "Data (bytes)",
+          "description": "The amount of data in bytes."
+        },
+        "balance": {
+          "type": "integer",
+          "maximum": 10000000000,
+          "minimum": 0,
+          "format": "int64",
+          "title": "Balance Top Up (cents)",
+          "description": "The balance to top up for the user. Must be zero or positive."
+        },
+        "price_total": {
+          "type": "integer",
+          "maximum": 10000000000,
+          "minimum": 1,
+          "format": "int64",
+          "title": "Price (cents)",
+          "description": "The total price of the invoice, including any discounts. Must be at least 1 cent."
+        },
+        "gateway": {
+          "allOf": [
+            {
+              "$ref": "#/components/schemas/InvoiceGatewayEnum"
+            }
+          ],
+          "title": "Payment Gateway",
+          "description": "The payment gateway used for processing the payment. * `coinbase` - Coinbase * `cryptomus` - Cryptomus * `stripe` - Stripe * `coingate` - Coingate * `wallet` - Wallet * `manual` - Manual * `whitepay` - Whitepay * `wayforpay` - WayForPay * `usegateway` - UseGateway * `binance` - Binance Pay * `anymoney` - Any.Money * `coinpayments` - CoinPayments * `checkoutcom` - Checkout.com * `nowpayments` - NOWPayments * `btcpay` - BTCPay Server * `braintree` - Braintree * `monobank` - monobank * `liqpay` - LiqPay * `iyzico` - iyzico * `paytr` - PayTR * `payu` - PayU * `tpay` - Tpay * `przelewy24` - Przelewy24 * `gopay` - GoPay * `comgate` - Comgate * `monei` - MONEI * `redsys` - Redsys * `payplug` - PayPlug * `mollie` - Mollie * `unzer` - Unzer * `payone` - PAYONE * `nexi_xpay` - Nexi XPay * `halyk_epay` - Halyk ePay * `kaspi_pay` - Kaspi Pay * `vipps_mobilepay` - Vipps MobilePay * `paytrail` - Paytrail"
+        },
+        "currency": {
+          "type": "string",
+          "title": "Billing Currency",
+          "description": "ISO 4217 currency captured when the invoice is created.",
+          "maxLength": 3
+        },
+        "provider_checkout_id": {
+          "type": "string",
+          "description": "Provider-side hosted checkout identifier used for reconciliation.",
+          "maxLength": 255
+        },
+        "provider_payment_id": {
+          "type": "string",
+          "description": "Provider-side payment or transaction identifier used for reconciliation.",
+          "maxLength": 255
+        },
+        "checkout_status": {
+          "$ref": "#/components/schemas/CheckoutStatusEnum"
+        },
+        "vat": {
+          "type": "number",
+          "format": "double",
+          "maximum": 100.0,
+          "minimum": 0.0,
+          "title": "VAT (%)",
+          "description": "The VAT percentage applied to the invoice. Must be between 0 and 100."
+        },
+        "company_name": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_address": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_city": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_postal_code": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_registration_number": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_vat_number": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "paid": {
+          "type": "string",
+          "format": "date-time",
+          "nullable": true,
+          "description": "The date and time when the invoice was paid."
+        },
+        "expires": {
+          "type": "string",
+          "format": "date-time",
+          "nullable": true,
+          "description": "The date and time when the invoice expires. If not set, the invoice does not expire."
+        }
+      },
+      "required": [
+        "country",
+        "coupon",
+        "created",
+        "updated"
+      ]
+    },
+    "InvoiceRead": {
+      "anyOf": [
+        {
+          "$ref": "#/components/schemas/Invoice"
+        },
+        {
+          "$ref": "#/components/schemas/InvoiceShort"
+        }
+      ],
+      "description": "Full invoice in package-based deployments; short invoice otherwise. Invoice creation always returns the full Invoice representation."
+    },
+    "User": {
+      "type": "object",
+      "description": "Customer account with contact details, security settings, package data, referral information, and managed sub-users visible to the caller.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "readOnly": true
+        },
+        "username": {
+          "type": "string",
+          "description": "Value must contain only letters, numbers, and underscores. It must not start or end with an underscore.",
+          "maxLength": 150
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "maxLength": 254
+        },
+        "is_reseller": {
+          "type": "boolean",
+          "title": "Reseller",
+          "description": "Reseller can create sub-users and manage their data."
+        },
+        "is_marketer": {
+          "type": "boolean",
+          "title": "Marketer",
+          "description": "Marketer can manage marketing campaigns and view analytics."
+        },
+        "is_superuser": {
+          "type": "boolean",
+          "title": "Superuser status",
+          "description": "Designates that this user has all permissions without explicitly assigning them."
+        },
+        "date_joined": {
+          "type": "string",
+          "format": "date-time",
+          "readOnly": true
+        },
+        "date_joined_ts": {
+          "type": "integer",
+          "description": "Timestamp of when the user joined",
+          "readOnly": true
+        },
+        "first_name": {
+          "type": "string",
+          "maxLength": 150
+        },
+        "last_name": {
+          "type": "string",
+          "maxLength": 150
+        },
+        "balance": {
+          "type": "integer",
+          "maximum": 2147483647,
+          "minimum": 0
+        },
+        "language": {
+          "$ref": "#/components/schemas/LanguageEnum"
+        },
+        "country": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "state": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "city": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "address": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "zip": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_name": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_address": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_city": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_postal_code": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_country": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "company_vat_number": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "allowed_ips": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of IP addresses allowed for this user",
+          "readOnly": true
+        },
+        "blocked_domains": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of domains blocked for this user",
+          "readOnly": true
+        },
+        "connection_limit": {
+          "type": "integer",
+          "maximum": 2147483647,
+          "minimum": -1,
+          "description": "The maximum number of concurrent connections allowed for this package."
+        },
+        "parent_id": {
+          "type": "string",
+          "description": "ID of the parent user (for sub-accounts)",
+          "readOnly": true
+        },
+        "sub_users": {
+          "type": "integer",
+          "description": "Number of sub-users managed by this reseller",
+          "readOnly": true
+        },
+        "referrals": {
+          "type": "integer",
+          "description": "Number of users referred by this user",
+          "readOnly": true
+        },
+        "referral_id": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "referral_code": {
+          "type": "string",
+          "readOnly": true
+        },
+        "referral_data_earned": {
+          "type": "integer",
+          "readOnly": true
+        },
+        "referral_data_pending": {
+          "type": "integer",
+          "readOnly": true
+        },
+        "referral_balance_pending": {
+          "type": "integer",
+          "readOnly": true
+        },
+        "referral_balance_earned": {
+          "type": "integer",
+          "readOnly": true
+        },
+        "currency": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Currency information for the user's transactions",
+          "readOnly": true
+        },
+        "coupons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": {}
+          },
+          "description": "Available coupons for this user",
+          "readOnly": true
+        },
+        "data": {
+          "type": "integer",
+          "nullable": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is disabled.",
+          "readOnly": true
+        },
+        "data_spent": {
+          "type": "integer",
+          "nullable": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is disabled.",
+          "readOnly": true
+        },
+        "data_updated": {
+          "type": "string",
+          "format": "date-time",
+          "nullable": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is disabled.",
+          "readOnly": true
+        },
+        "proxy_password": {
+          "type": "string",
+          "nullable": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is disabled.",
+          "readOnly": true
+        },
+        "proxy_password_reset": {
+          "type": "string",
+          "format": "date-time",
+          "nullable": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is disabled.",
+          "readOnly": true
+        },
+        "orders": {
+          "type": "array",
+          "items": {
+            "$ref": "#/components/schemas/Order"
+          },
+          "readOnly": true,
+          "description": "Present only when SITE_PACKAGE_BASED_AUTH is enabled."
+        }
+      },
+      "required": [
+        "allowed_ips",
+        "blocked_domains",
+        "coupons",
+        "currency",
+        "date_joined",
+        "date_joined_ts",
+        "email",
+        "id",
+        "parent_id",
+        "referral_balance_earned",
+        "referral_balance_pending",
+        "referral_code",
+        "referral_data_earned",
+        "referral_data_pending",
+        "referrals",
+        "sub_users",
+        "username"
+      ]
+    },
+    "UserPasswordResetRequestRequest": {
+      "type": "object",
+      "properties": {
+        "package_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Package whose proxy password should be rotated. Required only when package-based authentication is enabled."
+        }
+      }
+    }
+  }
+}