proxyrequest-sdk 1.0.0__py3-none-any.whl

proxyrequest_sdk/resources/webhooks.py

@@ -0,0 +1,114 @@
+# Generated by scripts/generate.py; do not edit.
+from __future__ import annotations
+
+from typing import Any, cast
+
+from ..files import FileDownload
+from .._generated.models.paginated_webhook_list import PaginatedWebhookList
+from .._generated.types import UNSET
+from .._generated.types import Unset
+from .._generated.models.webhook_create_request import WebhookCreateRequest
+from .._generated.models.webhook_created import WebhookCreated
+from .._generated.models.webhook_list import WebhookList
+from .._generated.api.webhooks import webhooks_create as _webhooks_create
+from .._generated.api.webhooks import webhooks_destroy as _webhooks_destroy
+from .._generated.api.webhooks import webhooks_retrieve as _webhooks_retrieve
+from .._generated.api.webhooks import webhooks_list as _webhooks_list
+
+
+class WebhooksResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self, *, body: WebhookCreateRequest, accept_language: str | Unset = UNSET
+    ) -> WebhookCreated:
+        """Create a customer webhook"""
+        return cast(
+            WebhookCreated,
+            self._client._call(
+                _webhooks_create.sync_detailed, body=body, accept_language=accept_language
+            ),
+        )
+
+    def delete(self, id: str, *, accept_language: str | Unset = UNSET) -> None:
+        """Delete a customer webhook"""
+        self._client._call(_webhooks_destroy.sync_detailed, id=id, accept_language=accept_language)
+        return None
+
+    def get(self, id: str, *, accept_language: str | Unset = UNSET) -> WebhookList:
+        """Get a customer webhook"""
+        return cast(
+            WebhookList,
+            self._client._call(
+                _webhooks_retrieve.sync_detailed, id=id, accept_language=accept_language
+            ),
+        )
+
+    def list(
+        self,
+        *,
+        limit: int | Unset = UNSET,
+        offset: int | Unset = UNSET,
+        accept_language: str | Unset = UNSET,
+    ) -> PaginatedWebhookList:
+        """List customer webhooks"""
+        return cast(
+            PaginatedWebhookList,
+            self._client._call(
+                _webhooks_list.sync_detailed,
+                limit=limit,
+                offset=offset,
+                accept_language=accept_language,
+            ),
+        )
+
+
+class AsyncWebhooksResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def create(
+        self, *, body: WebhookCreateRequest, accept_language: str | Unset = UNSET
+    ) -> WebhookCreated:
+        """Create a customer webhook"""
+        return cast(
+            WebhookCreated,
+            await self._client._call(
+                _webhooks_create.asyncio_detailed, body=body, accept_language=accept_language
+            ),
+        )
+
+    async def delete(self, id: str, *, accept_language: str | Unset = UNSET) -> None:
+        """Delete a customer webhook"""
+        await self._client._call(
+            _webhooks_destroy.asyncio_detailed, id=id, accept_language=accept_language
+        )
+        return None
+
+    async def get(self, id: str, *, accept_language: str | Unset = UNSET) -> WebhookList:
+        """Get a customer webhook"""
+        return cast(
+            WebhookList,
+            await self._client._call(
+                _webhooks_retrieve.asyncio_detailed, id=id, accept_language=accept_language
+            ),
+        )
+
+    async def list(
+        self,
+        *,
+        limit: int | Unset = UNSET,
+        offset: int | Unset = UNSET,
+        accept_language: str | Unset = UNSET,
+    ) -> PaginatedWebhookList:
+        """List customer webhooks"""
+        return cast(
+            PaginatedWebhookList,
+            await self._client._call(
+                _webhooks_list.asyncio_detailed,
+                limit=limit,
+                offset=offset,
+                accept_language=accept_language,
+            ),
+        )

proxyrequest_sdk/webhooks.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any
+
+from .errors import InvalidSignatureError
+
+
+class WebhookVerifier:
+    """Verify ProxyRequest webhook signatures against the exact raw request body."""
+
+    @staticmethod
+    def verify(
+        raw_body: bytes | str,
+        signature: str,
+        secret: str,
+        timestamp_header: str | None = None,
+        tolerance: int | None = 300,
+        now: int | None = None,
+    ) -> bool:
+        if not signature or not secret or (tolerance is not None and tolerance < 0):
+            return False
+        parsed = _parse_signature(signature)
+        if parsed is None:
+            return False
+        timestamp, received = parsed
+        if timestamp_header is not None:
+            header = timestamp_header.strip()
+            if not header.isdigit() or int(header) != timestamp:
+                return False
+        if (
+            tolerance is not None
+            and abs((int(time.time()) if now is None else now) - timestamp) > tolerance
+        ):
+            return False
+        body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+        expected = hmac.new(
+            secret.encode(), str(timestamp).encode() + b"." + body, hashlib.sha256
+        ).hexdigest()
+        return any(hmac.compare_digest(expected, candidate.lower()) for candidate in received)
+
+    @staticmethod
+    def verify_or_raise(
+        raw_body: bytes | str,
+        signature: str,
+        secret: str,
+        timestamp_header: str | None = None,
+        tolerance: int | None = 300,
+        now: int | None = None,
+    ) -> None:
+        if not WebhookVerifier.verify(
+            raw_body, signature, secret, timestamp_header, tolerance, now
+        ):
+            raise InvalidSignatureError("The ProxyRequest webhook signature is invalid or expired.")
+
+    @staticmethod
+    def decode_verified_json(
+        raw_body: bytes | str,
+        signature: str,
+        secret: str,
+        timestamp_header: str | None = None,
+        tolerance: int | None = 300,
+        now: int | None = None,
+    ) -> dict[str, Any]:
+        WebhookVerifier.verify_or_raise(
+            raw_body, signature, secret, timestamp_header, tolerance, now
+        )
+        try:
+            payload = json.loads(raw_body)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError("The verified webhook body is not valid JSON.") from error
+        if not isinstance(payload, dict) or not all(isinstance(key, str) for key in payload):
+            raise ValueError("The verified webhook payload must be a JSON object.")
+        return payload
+
+
+def _parse_signature(signature: str) -> tuple[int, list[str]] | None:
+    timestamp: int | None = None
+    signatures: list[str] = []
+    for part in signature.split(","):
+        pair = part.strip().split("=", 1)
+        if len(pair) != 2:
+            return None
+        key, value = pair
+        if key == "t":
+            if timestamp is not None or not value.isdigit() or len(value) > 19:
+                return None
+            timestamp = int(value)
+        elif key == "v1" and re.fullmatch(r"[a-fA-F0-9]{64}", value):
+            signatures.append(value)
+    return (timestamp, signatures) if timestamp is not None and signatures else None

proxyrequest_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: proxyrequest-sdk
+Version: 1.0.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/
+Project-URL: Repository, https://github.com/proxyrequest/python-sdk
+Project-URL: Issues, https://github.com/proxyrequest/python-sdk/issues
+Project-URL: Changelog, https://github.com/proxyrequest/python-sdk/blob/main/CHANGELOG.md
+Author-email: ProxyRequest <support@proxyrequest.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,proxy,proxyrequest,residential-proxy,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=23.2
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.8
+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/)
+
+Official synchronous and asynchronous Python client for the
+[ProxyRequest](https://proxyrequest.com/) public API. It covers all 82 operations
+in the current contract: users, orders, proxy generation, analytics, invoices,
+packages, locations, webhooks, API keys, Telegram integration, and more.
+
+## What is ProxyRequest?
+
+ProxyRequest is a white-label proxy platform for operators and resellers that
+already have upstream proxy supply. It provides the product and control layer
+needed to turn that supply into a customer-facing service:
+
+- managed HTTP, HTTPS, SOCKS5, and SOCKS5h gateways;
+- packages, users, orders, proxy credentials, limits, and byte accounting;
+- geographic and network targeting, sticky sessions, and multi-provider routing;
+- customer and reseller dashboards, invoices, coupons, and payment flows;
+- analytics, signed webhooks, API keys, and operational reporting.
+
+You can use the complete managed backend and customer dashboard, or keep your
+own frontend, identity, and billing while ProxyRequest handles provisioning,
+routing, accounting, and analytics headlessly. You retain your brand, pricing,
+customer relationships, and upstream provider contracts.
+
+ProxyRequest is not an upstream bandwidth plan. Provider traffic and contracts
+remain separate from the platform subscription. See the
+[platform overview](https://proxyrequest.com/docs/) for the complete operating
+boundary.
+
+## How this SDK fits
+
+The REST API is the control plane around proxy traffic. This SDK provisions
+resources and reads their state; customer proxy requests go to the managed
+gateway servers instead of passing through the SDK or REST API.
+
+```text
+Your Python backend ── HTTPS/JSON ──> ProxyRequest API
+Customer traffic ───── HTTP/SOCKS ──> Managed gateways ──> Destination
+```
+
+Keep the credentials for those paths separate: API keys belong only in trusted
+backend code, while generated proxy usernames and passwords are supplied only
+to the customer or workload that connects to a gateway.
+
+The most important resource relationships are:
+
+```text
+Customer purchase:
+Package -> Invoice -> Paid invoice -> Order / data ledger -> Proxy credentials
+
+Reseller provisioning:
+Eligible root order -> Sub-user + child allocation -> Proxy credentials
+```
+
+Invoices describe commercial state. Orders and data ledgers describe service
+entitlement. Creating an invoice or returning from checkout is therefore not
+proof that proxy access is active.
+
+## Choose an integration path
+
+| Scenario | Recommended flow |
+| --- | --- |
+| Built-in customer checkout | Select a package, create an invoice, obtain its payment link, confirm payment and entitlement, then generate proxy credentials. |
+| Reseller-managed customer | Create a sub-user, assign a package and byte limit from an eligible root order, then generate credentials for that user. |
+| Existing headless platform | Keep your own customer and billing records, persist mappings to ProxyRequest users/packages/orders, and provision through the API. |
+
+See [purchase a package with an invoice](https://github.com/proxyrequest/python-sdk/blob/main/docs/guides/purchase-flow.md)
+and [provision a reseller customer](https://github.com/proxyrequest/python-sdk/blob/main/docs/guides/reseller-provisioning.md)
+for complete Python examples.
+
+## Installation
+
+```bash
+python -m pip install proxyrequest-sdk
+```
+
+Python 3.11 or newer is required. The package uses `httpx` and includes both
+sync and async clients.
+
+## Quick start
+
+```python
+import os
+
+from proxyrequest_sdk import Client
+from proxyrequest_sdk.models import UserCreateRequest
+
+with Client.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
+    profile = client.profile.get()
+    user = client.users.create(
+        body=UserCreateRequest(
+            username="customer-reference",
+            password=os.urandom(32).hex(),
+        )
+    )
+    print(profile.username, user.id)
+```
+
+Static API keys are sent as `Authorization: Static YOUR_API_KEY`. Never expose
+them to browser code.
+
+The asynchronous API has the same resource and method names:
+
+```python
+import os
+
+from proxyrequest_sdk import AsyncClient
+
+
+async def list_users() -> None:
+    async with AsyncClient.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
+        page = await client.users.list(limit=100)
+        for user in page.results:
+            print(user.username)
+```
+
+## Resource API
+
+`Client` and `AsyncClient` expose one object per API group:
+
+```python
+client.authorization
+client.users
+client.profile
+client.orders
+client.proxies
+client.analytics
+client.invoices
+client.coupons
+client.rewards
+client.affiliates
+client.packages
+client.locations
+client.api_keys
+client.webhooks
+client.telegram
+client.telegram_service
+client.sessions
+client.settings
+client.news
+```
+
+All operation parameters and return values are typed. Request and response
+models live in `proxyrequest_sdk.models`, use snake_case attributes, and expose
+`to_dict()` / `from_dict()` helpers. IDs follow their OpenAPI type (`UUID` or
+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).
+
+## Pagination
+
+List endpoints return their typed OpenAPI page. Use `paginate()` to follow all
+pages lazily:
+
+```python
+with Client.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
+    for user in client.paginate(client.users.list, limit=100):
+        print(user.username)
+```
+
+The asynchronous variant is also lazy:
+
+```python
+async with AsyncClient.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
+    async for user in client.paginate(client.users.list, limit=100):
+        print(user.username)
+```
+
+## Errors
+
+Every documented and undocumented HTTP failure is normalized to `ApiError`.
+Network and decoding problems use the same contract:
+
+```python
+from proxyrequest_sdk import ApiError, ErrorKind
+
+try:
+    client.profile.get()
+except ApiError as error:
+    if error.kind is ErrorKind.AUTHENTICATION:
+        # Replace the invalid API key or bearer token.
+        pass
+    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.
+
+## Configuration and custom deployments
+
+```python
+import httpx
+
+client = Client.with_api_key(
+    os.environ["PROXYREQUEST_API_KEY"],
+    base_url="https://customer-api.example/api/v1",
+    language="uk",
+    timeout=20,
+    connect_timeout=5,
+)
+```
+
+An existing `httpx.Client` or `httpx.AsyncClient` can be supplied through
+`http_client`. It must have the same `base_url`; the SDK applies its auth,
+language, and user-agent headers but leaves closing the external client to the
+caller. The `request()` method is an authenticated escape hatch for endpoints
+introduced before the next SDK release.
+
+## Invoice downloads
+
+```python
+download = client.download_invoice_pdf(invoice_id)
+path = download.save(f"./{download.filename}")
+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:
+
+```python
+from proxyrequest_sdk import WebhookVerifier
+
+payload = WebhookVerifier.decode_verified_json(
+    raw_body,
+    request.headers.get("X-Webhook-Signature", ""),
+    os.environ["PROXYREQUEST_WEBHOOK_SECRET"],
+    timestamp_header=request.headers.get("X-Webhook-Timestamp"),
+)
+```
+
+## Platform documentation
+
+- [Platform documentation](https://proxyrequest.com/docs/): capabilities,
+  responsibility boundaries, deployment modes, and starting points.
+- [Integration overview](https://proxyrequest.com/docs/integration/overview/):
+  control-plane boundary and common API flows.
+- [API fundamentals](https://proxyrequest.com/docs/integration/api-fundamentals/)
+  and [API resource map](https://proxyrequest.com/docs/integration/api-resource-map/):
+  authentication, errors, pagination, and resource relationships.
+- [Billing and growth](https://proxyrequest.com/docs/integration/billing-and-growth/):
+  invoices, payment links, coupons, and entitlement reconciliation.
+- [Reseller workflow](https://proxyrequest.com/docs/integration/reseller-workflow/)
+  and [users and data](https://proxyrequest.com/docs/integration/users-and-data/):
+  sub-user provisioning and safe byte allocation.
+- [Catalog and proxy generation](https://proxyrequest.com/docs/integration/catalog-and-proxies/):
+  packages, orders, locations, and credentials.
+- [Webhooks](https://proxyrequest.com/docs/integration/webhooks/) and
+  [usage accounting](https://proxyrequest.com/docs/proxy/usage-accounting/):
+  event handling, root ledgers, child limits, and reconciliation.
+- [API reference](https://proxyrequest.com/docs/api/): exact endpoints,
+  request schemas, responses, and examples.
+
+## Development
+
+```bash
+uv sync --all-groups
+make quality
+make generate-check
+make build
+```
+
+The vendored schema is pinned in `openapi/source.json`. Run
+`make sync-openapi SOURCE=/path/to/openapi.yml`, followed by `make generate`, to
+update it. Generation is pinned and CI rejects uncommitted contract changes.
+
+## License
+
+MIT