proxyrequest-sdk 1.0.0__tar.gz

proxyrequest_sdk-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+htmlcov/
+.coverage
+.DS_Store

proxyrequest_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to the ProxyRequest Python SDK are documented here.
+
+## 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/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Install [uv](https://docs.astral.sh/uv/), then create the development
+environment and run the complete verification suite:
+
+```bash
+uv sync --all-groups
+make quality
+make generate-check
+make build
+```
+
+Generated code lives under `src/proxyrequest_sdk/_generated`, `models`, and
+`resources`. Do not edit it directly. Update the canonical schema with
+`make sync-openapi SOURCE=/path/to/openapi.yml`, run `make generate`, and review
+the resulting contract and public API changes.
+
+Submit changes through a pull request. Add tests for behavioral changes and
+keep backward compatibility unless the release is explicitly major.

proxyrequest_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyRequest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proxyrequest_sdk-1.0.0/Makefile

@@ -0,0 +1,33 @@
+.PHONY: sync-openapi generate generate-check format format-check lint typecheck test quality build
+
+sync-openapi:
+	uv run python scripts/sync_openapi.py $(SOURCE)
+
+generate:
+	uv run python scripts/generate.py
+
+generate-check:
+	uv run python scripts/check_generated.py
+
+format:
+	uv run ruff check --fix src tests scripts
+	uv run ruff format src tests scripts
+
+format-check:
+	uv run ruff format --check src tests scripts
+
+lint:
+	uv run ruff check src tests scripts
+
+typecheck:
+	uv run mypy
+
+test:
+	uv run pytest
+
+quality: format-check lint typecheck test
+
+build:
+	rm -rf build dist
+	uv run python -m build
+	uv run twine check dist/*

proxyrequest_sdk-1.0.0/PKG-INFO

@@ -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