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

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

@@ -4,6 +4,13 @@ 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyrequest-sdk
-Version: 2.1.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/
@@ -39,6 +39,9 @@ Official synchronous and asynchronous Python client for the
 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

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

@@ -9,6 +9,9 @@ Official synchronous and asynchronous Python client for the
 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

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.1.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.